Add files using upload-large-folder tool

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

.venv/lib/python3.13/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) -> Expr: # type: ignore
+
+        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

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

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

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

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

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

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

@@ -0,0 +1,164 @@
+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

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

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

.venv/lib/python3.13/site-packages/sympy/calculus/util.py

@@ -0,0 +1,895 @@
+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("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_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))
+
+            critical_points = solveset(f.diff(symbol), symbol, interval)
+
+            if not iterable(critical_points):
+                raise NotImplementedError(
+                        'Unable to find critical points for {}'.format(f))
+            if isinstance(critical_points, ImageSet):
+                raise NotImplementedError(
+                        'Infinite number of critical points for {}'.format(f))
+
+            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("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)

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

@@ -0,0 +1,33 @@
+"""
+Category Theory module.
+
+Provides some of the fundamental category-theory-related classes,
+including categories, morphisms, diagrams.  Functors are not
+implemented yet.
+
+The general reference work this module tries to follow is
+
+  [JoyOfCats] J. Adamek, H. Herrlich. G. E. Strecker: Abstract and
+              Concrete Categories. The Joy of Cats.
+
+The latest version of this book should be available for free download
+from
+
+   katmat.math.uni-bremen.de/acc/acc.pdf
+
+"""
+
+from .baseclasses import (Object, Morphism, IdentityMorphism,
+                         NamedMorphism, CompositeMorphism, Category,
+                         Diagram)
+
+from .diagram_drawing import (DiagramGrid, XypicDiagramDrawer,
+                             xypic_draw_diagram, preview_diagram)
+
+__all__ = [
+    'Object', 'Morphism', 'IdentityMorphism', 'NamedMorphism',
+    'CompositeMorphism', 'Category', 'Diagram',
+
+    'DiagramGrid', 'XypicDiagramDrawer', 'xypic_draw_diagram',
+    'preview_diagram',
+]

.venv/lib/python3.13/site-packages/sympy/categories/baseclasses.py

@@ -0,0 +1,978 @@
+from sympy.core import S, Basic, Dict, Symbol, Tuple, sympify
+from sympy.core.symbol import Str
+from sympy.sets import Set, FiniteSet, EmptySet
+from sympy.utilities.iterables import iterable
+
+
+class Class(Set):
+    r"""
+    The base class for any kind of class in the set-theoretic sense.
+
+    Explanation
+    ===========
+
+    In axiomatic set theories, everything is a class.  A class which
+    can be a member of another class is a set.  A class which is not a
+    member of another class is a proper class.  The class `\{1, 2\}`
+    is a set; the class of all sets is a proper class.
+
+    This class is essentially a synonym for :class:`sympy.core.Set`.
+    The goal of this class is to assure easier migration to the
+    eventual proper implementation of set theory.
+    """
+    is_proper = False
+
+
+class Object(Symbol):
+    """
+    The base class for any kind of object in an abstract category.
+
+    Explanation
+    ===========
+
+    While technically any instance of :class:`~.Basic` will do, this
+    class is the recommended way to create abstract objects in
+    abstract categories.
+    """
+
+
+class Morphism(Basic):
+    """
+    The base class for any morphism in an abstract category.
+
+    Explanation
+    ===========
+
+    In abstract categories, a morphism is an arrow between two
+    category objects.  The object where the arrow starts is called the
+    domain, while the object where the arrow ends is called the
+    codomain.
+
+    Two morphisms between the same pair of objects are considered to
+    be the same morphisms.  To distinguish between morphisms between
+    the same objects use :class:`NamedMorphism`.
+
+    It is prohibited to instantiate this class.  Use one of the
+    derived classes instead.
+
+    See Also
+    ========
+
+    IdentityMorphism, NamedMorphism, CompositeMorphism
+    """
+    def __new__(cls, domain, codomain):
+        raise(NotImplementedError(
+            "Cannot instantiate Morphism.  Use derived classes instead."))
+
+    @property
+    def domain(self):
+        """
+        Returns the domain of the morphism.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> f.domain
+        Object("A")
+
+        """
+        return self.args[0]
+
+    @property
+    def codomain(self):
+        """
+        Returns the codomain of the morphism.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> f.codomain
+        Object("B")
+
+        """
+        return self.args[1]
+
+    def compose(self, other):
+        r"""
+        Composes self with the supplied morphism.
+
+        The order of elements in the composition is the usual order,
+        i.e., to construct `g\circ f` use ``g.compose(f)``.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> g * f
+        CompositeMorphism((NamedMorphism(Object("A"), Object("B"), "f"),
+        NamedMorphism(Object("B"), Object("C"), "g")))
+        >>> (g * f).domain
+        Object("A")
+        >>> (g * f).codomain
+        Object("C")
+
+        """
+        return CompositeMorphism(other, self)
+
+    def __mul__(self, other):
+        r"""
+        Composes self with the supplied morphism.
+
+        The semantics of this operation is given by the following
+        equation: ``g * f == g.compose(f)`` for composable morphisms
+        ``g`` and ``f``.
+
+        See Also
+        ========
+
+        compose
+        """
+        return self.compose(other)
+
+
+class IdentityMorphism(Morphism):
+    """
+    Represents an identity morphism.
+
+    Explanation
+    ===========
+
+    An identity morphism is a morphism with equal domain and codomain,
+    which acts as an identity with respect to composition.
+
+    Examples
+    ========
+
+    >>> from sympy.categories import Object, NamedMorphism, IdentityMorphism
+    >>> A = Object("A")
+    >>> B = Object("B")
+    >>> f = NamedMorphism(A, B, "f")
+    >>> id_A = IdentityMorphism(A)
+    >>> id_B = IdentityMorphism(B)
+    >>> f * id_A == f
+    True
+    >>> id_B * f == f
+    True
+
+    See Also
+    ========
+
+    Morphism
+    """
+    def __new__(cls, domain):
+        return Basic.__new__(cls, domain)
+
+    @property
+    def codomain(self):
+        return self.domain
+
+
+class NamedMorphism(Morphism):
+    """
+    Represents a morphism which has a name.
+
+    Explanation
+    ===========
+
+    Names are used to distinguish between morphisms which have the
+    same domain and codomain: two named morphisms are equal if they
+    have the same domains, codomains, and names.
+
+    Examples
+    ========
+
+    >>> from sympy.categories import Object, NamedMorphism
+    >>> A = Object("A")
+    >>> B = Object("B")
+    >>> f = NamedMorphism(A, B, "f")
+    >>> f
+    NamedMorphism(Object("A"), Object("B"), "f")
+    >>> f.name
+    'f'
+
+    See Also
+    ========
+
+    Morphism
+    """
+    def __new__(cls, domain, codomain, name):
+        if not name:
+            raise ValueError("Empty morphism names not allowed.")
+
+        if not isinstance(name, Str):
+            name = Str(name)
+
+        return Basic.__new__(cls, domain, codomain, name)
+
+    @property
+    def name(self):
+        """
+        Returns the name of the morphism.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> f.name
+        'f'
+
+        """
+        return self.args[2].name
+
+
+class CompositeMorphism(Morphism):
+    r"""
+    Represents a morphism which is a composition of other morphisms.
+
+    Explanation
+    ===========
+
+    Two composite morphisms are equal if the morphisms they were
+    obtained from (components) are the same and were listed in the
+    same order.
+
+    The arguments to the constructor for this class should be listed
+    in diagram order: to obtain the composition `g\circ f` from the
+    instances of :class:`Morphism` ``g`` and ``f`` use
+    ``CompositeMorphism(f, g)``.
+
+    Examples
+    ========
+
+    >>> from sympy.categories import Object, NamedMorphism, CompositeMorphism
+    >>> A = Object("A")
+    >>> B = Object("B")
+    >>> C = Object("C")
+    >>> f = NamedMorphism(A, B, "f")
+    >>> g = NamedMorphism(B, C, "g")
+    >>> g * f
+    CompositeMorphism((NamedMorphism(Object("A"), Object("B"), "f"),
+    NamedMorphism(Object("B"), Object("C"), "g")))
+    >>> CompositeMorphism(f, g) == g * f
+    True
+
+    """
+    @staticmethod
+    def _add_morphism(t, morphism):
+        """
+        Intelligently adds ``morphism`` to tuple ``t``.
+
+        Explanation
+        ===========
+
+        If ``morphism`` is a composite morphism, its components are
+        added to the tuple.  If ``morphism`` is an identity, nothing
+        is added to the tuple.
+
+        No composability checks are performed.
+        """
+        if isinstance(morphism, CompositeMorphism):
+            # ``morphism`` is a composite morphism; we have to
+            # denest its components.
+            return t + morphism.components
+        elif isinstance(morphism, IdentityMorphism):
+            # ``morphism`` is an identity.  Nothing happens.
+            return t
+        else:
+            return t + Tuple(morphism)
+
+    def __new__(cls, *components):
+        if components and not isinstance(components[0], Morphism):
+            # Maybe the user has explicitly supplied a list of
+            # morphisms.
+            return CompositeMorphism.__new__(cls, *components[0])
+
+        normalised_components = Tuple()
+
+        for current, following in zip(components, components[1:]):
+            if not isinstance(current, Morphism) or \
+                    not isinstance(following, Morphism):
+                raise TypeError("All components must be morphisms.")
+
+            if current.codomain != following.domain:
+                raise ValueError("Uncomposable morphisms.")
+
+            normalised_components = CompositeMorphism._add_morphism(
+                normalised_components, current)
+
+        # We haven't added the last morphism to the list of normalised
+        # components.  Add it now.
+        normalised_components = CompositeMorphism._add_morphism(
+            normalised_components, components[-1])
+
+        if not normalised_components:
+            # If ``normalised_components`` is empty, only identities
+            # were supplied.  Since they all were composable, they are
+            # all the same identities.
+            return components[0]
+        elif len(normalised_components) == 1:
+            # No sense to construct a whole CompositeMorphism.
+            return normalised_components[0]
+
+        return Basic.__new__(cls, normalised_components)
+
+    @property
+    def components(self):
+        """
+        Returns the components of this composite morphism.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> (g * f).components
+        (NamedMorphism(Object("A"), Object("B"), "f"),
+        NamedMorphism(Object("B"), Object("C"), "g"))
+
+        """
+        return self.args[0]
+
+    @property
+    def domain(self):
+        """
+        Returns the domain of this composite morphism.
+
+        The domain of the composite morphism is the domain of its
+        first component.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> (g * f).domain
+        Object("A")
+
+        """
+        return self.components[0].domain
+
+    @property
+    def codomain(self):
+        """
+        Returns the codomain of this composite morphism.
+
+        The codomain of the composite morphism is the codomain of its
+        last component.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> (g * f).codomain
+        Object("C")
+
+        """
+        return self.components[-1].codomain
+
+    def flatten(self, new_name):
+        """
+        Forgets the composite structure of this morphism.
+
+        Explanation
+        ===========
+
+        If ``new_name`` is not empty, returns a :class:`NamedMorphism`
+        with the supplied name, otherwise returns a :class:`Morphism`.
+        In both cases the domain of the new morphism is the domain of
+        this composite morphism and the codomain of the new morphism
+        is the codomain of this composite morphism.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> (g * f).flatten("h")
+        NamedMorphism(Object("A"), Object("C"), "h")
+
+        """
+        return NamedMorphism(self.domain, self.codomain, new_name)
+
+
+class Category(Basic):
+    r"""
+    An (abstract) category.
+
+    Explanation
+    ===========
+
+    A category [JoyOfCats] is a quadruple `\mbox{K} = (O, \hom, id,
+    \circ)` consisting of
+
+    * a (set-theoretical) class `O`, whose members are called
+      `K`-objects,
+
+    * for each pair `(A, B)` of `K`-objects, a set `\hom(A, B)` whose
+      members are called `K`-morphisms from `A` to `B`,
+
+    * for a each `K`-object `A`, a morphism `id:A\rightarrow A`,
+      called the `K`-identity of `A`,
+
+    * a composition law `\circ` associating with every `K`-morphisms
+      `f:A\rightarrow B` and `g:B\rightarrow C` a `K`-morphism `g\circ
+      f:A\rightarrow C`, called the composite of `f` and `g`.
+
+    Composition is associative, `K`-identities are identities with
+    respect to composition, and the sets `\hom(A, B)` are pairwise
+    disjoint.
+
+    This class knows nothing about its objects and morphisms.
+    Concrete cases of (abstract) categories should be implemented as
+    classes derived from this one.
+
+    Certain instances of :class:`Diagram` can be asserted to be
+    commutative in a :class:`Category` by supplying the argument
+    ``commutative_diagrams`` in the constructor.
+
+    Examples
+    ========
+
+    >>> from sympy.categories import Object, NamedMorphism, Diagram, Category
+    >>> from sympy import FiniteSet
+    >>> A = Object("A")
+    >>> B = Object("B")
+    >>> C = Object("C")
+    >>> f = NamedMorphism(A, B, "f")
+    >>> g = NamedMorphism(B, C, "g")
+    >>> d = Diagram([f, g])
+    >>> K = Category("K", commutative_diagrams=[d])
+    >>> K.commutative_diagrams == FiniteSet(d)
+    True
+
+    See Also
+    ========
+
+    Diagram
+    """
+    def __new__(cls, name, objects=EmptySet, commutative_diagrams=EmptySet):
+        if not name:
+            raise ValueError("A Category cannot have an empty name.")
+
+        if not isinstance(name, Str):
+            name = Str(name)
+
+        if not isinstance(objects, Class):
+            objects = Class(objects)
+
+        new_category = Basic.__new__(cls, name, objects,
+                                     FiniteSet(*commutative_diagrams))
+        return new_category
+
+    @property
+    def name(self):
+        """
+        Returns the name of this category.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Category
+        >>> K = Category("K")
+        >>> K.name
+        'K'
+
+        """
+        return self.args[0].name
+
+    @property
+    def objects(self):
+        """
+        Returns the class of objects of this category.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, Category
+        >>> from sympy import FiniteSet
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> K = Category("K", FiniteSet(A, B))
+        >>> K.objects
+        Class({Object("A"), Object("B")})
+
+        """
+        return self.args[1]
+
+    @property
+    def commutative_diagrams(self):
+        """
+        Returns the :class:`~.FiniteSet` of diagrams which are known to
+        be commutative in this category.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism, Diagram, Category
+        >>> from sympy import FiniteSet
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> d = Diagram([f, g])
+        >>> K = Category("K", commutative_diagrams=[d])
+        >>> K.commutative_diagrams == FiniteSet(d)
+        True
+
+        """
+        return self.args[2]
+
+    def hom(self, A, B):
+        raise NotImplementedError(
+            "hom-sets are not implemented in Category.")
+
+    def all_morphisms(self):
+        raise NotImplementedError(
+            "Obtaining the class of morphisms is not implemented in Category.")
+
+
+class Diagram(Basic):
+    r"""
+    Represents a diagram in a certain category.
+
+    Explanation
+    ===========
+
+    Informally, a diagram is a collection of objects of a category and
+    certain morphisms between them.  A diagram is still a monoid with
+    respect to morphism composition; i.e., identity morphisms, as well
+    as all composites of morphisms included in the diagram belong to
+    the diagram.  For a more formal approach to this notion see
+    [Pare1970].
+
+    The components of composite morphisms are also added to the
+    diagram.  No properties are assigned to such morphisms by default.
+
+    A commutative diagram is often accompanied by a statement of the
+    following kind: "if such morphisms with such properties exist,
+    then such morphisms which such properties exist and the diagram is
+    commutative".  To represent this, an instance of :class:`Diagram`
+    includes a collection of morphisms which are the premises and
+    another collection of conclusions.  ``premises`` and
+    ``conclusions`` associate morphisms belonging to the corresponding
+    categories with the :class:`~.FiniteSet`'s of their properties.
+
+    The set of properties of a composite morphism is the intersection
+    of the sets of properties of its components.  The domain and
+    codomain of a conclusion morphism should be among the domains and
+    codomains of the morphisms listed as the premises of a diagram.
+
+    No checks are carried out of whether the supplied object and
+    morphisms do belong to one and the same category.
+
+    Examples
+    ========
+
+    >>> from sympy.categories import Object, NamedMorphism, Diagram
+    >>> from sympy import pprint, default_sort_key
+    >>> A = Object("A")
+    >>> B = Object("B")
+    >>> C = Object("C")
+    >>> f = NamedMorphism(A, B, "f")
+    >>> g = NamedMorphism(B, C, "g")
+    >>> d = Diagram([f, g])
+    >>> premises_keys = sorted(d.premises.keys(), key=default_sort_key)
+    >>> pprint(premises_keys, use_unicode=False)
+    [g*f:A-->C, id:A-->A, id:B-->B, id:C-->C, f:A-->B, g:B-->C]
+    >>> pprint(d.premises, use_unicode=False)
+    {g*f:A-->C: EmptySet, id:A-->A: EmptySet, id:B-->B: EmptySet,
+     id:C-->C: EmptySet, f:A-->B: EmptySet, g:B-->C: EmptySet}
+    >>> d = Diagram([f, g], {g * f: "unique"})
+    >>> pprint(d.conclusions,use_unicode=False)
+    {g*f:A-->C: {unique}}
+
+    References
+    ==========
+
+    [Pare1970] B. Pareigis: Categories and functors.  Academic Press, 1970.
+
+    """
+    @staticmethod
+    def _set_dict_union(dictionary, key, value):
+        """
+        If ``key`` is in ``dictionary``, set the new value of ``key``
+        to be the union between the old value and ``value``.
+        Otherwise, set the value of ``key`` to ``value.
+
+        Returns ``True`` if the key already was in the dictionary and
+        ``False`` otherwise.
+        """
+        if key in dictionary:
+            dictionary[key] = dictionary[key] | value
+            return True
+        else:
+            dictionary[key] = value
+            return False
+
+    @staticmethod
+    def _add_morphism_closure(morphisms, morphism, props, add_identities=True,
+                              recurse_composites=True):
+        """
+        Adds a morphism and its attributes to the supplied dictionary
+        ``morphisms``.  If ``add_identities`` is True, also adds the
+        identity morphisms for the domain and the codomain of
+        ``morphism``.
+        """
+        if not Diagram._set_dict_union(morphisms, morphism, props):
+            # We have just added a new morphism.
+
+            if isinstance(morphism, IdentityMorphism):
+                if props:
+                    # Properties for identity morphisms don't really
+                    # make sense, because very much is known about
+                    # identity morphisms already, so much that they
+                    # are trivial.  Having properties for identity
+                    # morphisms would only be confusing.
+                    raise ValueError(
+                        "Instances of IdentityMorphism cannot have properties.")
+                return
+
+            if add_identities:
+                empty = EmptySet
+
+                id_dom = IdentityMorphism(morphism.domain)
+                id_cod = IdentityMorphism(morphism.codomain)
+
+                Diagram._set_dict_union(morphisms, id_dom, empty)
+                Diagram._set_dict_union(morphisms, id_cod, empty)
+
+            for existing_morphism, existing_props in list(morphisms.items()):
+                new_props = existing_props & props
+                if morphism.domain == existing_morphism.codomain:
+                    left = morphism * existing_morphism
+                    Diagram._set_dict_union(morphisms, left, new_props)
+                if morphism.codomain == existing_morphism.domain:
+                    right = existing_morphism * morphism
+                    Diagram._set_dict_union(morphisms, right, new_props)
+
+            if isinstance(morphism, CompositeMorphism) and recurse_composites:
+                # This is a composite morphism, add its components as
+                # well.
+                empty = EmptySet
+                for component in morphism.components:
+                    Diagram._add_morphism_closure(morphisms, component, empty,
+                                                  add_identities)
+
+    def __new__(cls, *args):
+        """
+        Construct a new instance of Diagram.
+
+        Explanation
+        ===========
+
+        If no arguments are supplied, an empty diagram is created.
+
+        If at least an argument is supplied, ``args[0]`` is
+        interpreted as the premises of the diagram.  If ``args[0]`` is
+        a list, it is interpreted as a list of :class:`Morphism`'s, in
+        which each :class:`Morphism` has an empty set of properties.
+        If ``args[0]`` is a Python dictionary or a :class:`Dict`, it
+        is interpreted as a dictionary associating to some
+        :class:`Morphism`'s some properties.
+
+        If at least two arguments are supplied ``args[1]`` is
+        interpreted as the conclusions of the diagram.  The type of
+        ``args[1]`` is interpreted in exactly the same way as the type
+        of ``args[0]``.  If only one argument is supplied, the diagram
+        has no conclusions.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism
+        >>> from sympy.categories import IdentityMorphism, Diagram
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> d = Diagram([f, g])
+        >>> IdentityMorphism(A) in d.premises.keys()
+        True
+        >>> g * f in d.premises.keys()
+        True
+        >>> d = Diagram([f, g], {g * f: "unique"})
+        >>> d.conclusions[g * f]
+        {unique}
+
+        """
+        premises = {}
+        conclusions = {}
+
+        # Here we will keep track of the objects which appear in the
+        # premises.
+        objects = EmptySet
+
+        if len(args) >= 1:
+            # We've got some premises in the arguments.
+            premises_arg = args[0]
+
+            if isinstance(premises_arg, list):
+                # The user has supplied a list of morphisms, none of
+                # which have any attributes.
+                empty = EmptySet
+
+                for morphism in premises_arg:
+                    objects |= FiniteSet(morphism.domain, morphism.codomain)
+                    Diagram._add_morphism_closure(premises, morphism, empty)
+            elif isinstance(premises_arg, (dict, Dict)):
+                # The user has supplied a dictionary of morphisms and
+                # their properties.
+                for morphism, props in premises_arg.items():
+                    objects |= FiniteSet(morphism.domain, morphism.codomain)
+                    Diagram._add_morphism_closure(
+                        premises, morphism, FiniteSet(*props) if iterable(props) else FiniteSet(props))
+
+        if len(args) >= 2:
+            # We also have some conclusions.
+            conclusions_arg = args[1]
+
+            if isinstance(conclusions_arg, list):
+                # The user has supplied a list of morphisms, none of
+                # which have any attributes.
+                empty = EmptySet
+
+                for morphism in conclusions_arg:
+                    # Check that no new objects appear in conclusions.
+                    if ((sympify(objects.contains(morphism.domain)) is S.true) and
+                        (sympify(objects.contains(morphism.codomain)) is S.true)):
+                        # No need to add identities and recurse
+                        # composites this time.
+                        Diagram._add_morphism_closure(
+                            conclusions, morphism, empty, add_identities=False,
+                            recurse_composites=False)
+            elif isinstance(conclusions_arg, (dict, Dict)):
+                # The user has supplied a dictionary of morphisms and
+                # their properties.
+                for morphism, props in conclusions_arg.items():
+                    # Check that no new objects appear in conclusions.
+                    if (morphism.domain in objects) and \
+                       (morphism.codomain in objects):
+                        # No need to add identities and recurse
+                        # composites this time.
+                        Diagram._add_morphism_closure(
+                            conclusions, morphism, FiniteSet(*props) if iterable(props) else FiniteSet(props),
+                            add_identities=False, recurse_composites=False)
+
+        return Basic.__new__(cls, Dict(premises), Dict(conclusions), objects)
+
+    @property
+    def premises(self):
+        """
+        Returns the premises of this diagram.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism
+        >>> from sympy.categories import IdentityMorphism, Diagram
+        >>> from sympy import pretty
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> id_A = IdentityMorphism(A)
+        >>> id_B = IdentityMorphism(B)
+        >>> d = Diagram([f])
+        >>> print(pretty(d.premises, use_unicode=False))
+        {id:A-->A: EmptySet, id:B-->B: EmptySet, f:A-->B: EmptySet}
+
+        """
+        return self.args[0]
+
+    @property
+    def conclusions(self):
+        """
+        Returns the conclusions of this diagram.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism
+        >>> from sympy.categories import IdentityMorphism, Diagram
+        >>> from sympy import FiniteSet
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> d = Diagram([f, g])
+        >>> IdentityMorphism(A) in d.premises.keys()
+        True
+        >>> g * f in d.premises.keys()
+        True
+        >>> d = Diagram([f, g], {g * f: "unique"})
+        >>> d.conclusions[g * f] == FiniteSet("unique")
+        True
+
+        """
+        return self.args[1]
+
+    @property
+    def objects(self):
+        """
+        Returns the :class:`~.FiniteSet` of objects that appear in this
+        diagram.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism, Diagram
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> d = Diagram([f, g])
+        >>> d.objects
+        {Object("A"), Object("B"), Object("C")}
+
+        """
+        return self.args[2]
+
+    def hom(self, A, B):
+        """
+        Returns a 2-tuple of sets of morphisms between objects ``A`` and
+        ``B``: one set of morphisms listed as premises, and the other set
+        of morphisms listed as conclusions.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism, Diagram
+        >>> from sympy import pretty
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> d = Diagram([f, g], {g * f: "unique"})
+        >>> print(pretty(d.hom(A, C), use_unicode=False))
+        ({g*f:A-->C}, {g*f:A-->C})
+
+        See Also
+        ========
+        Object, Morphism
+        """
+        premises = EmptySet
+        conclusions = EmptySet
+
+        for morphism in self.premises.keys():
+            if (morphism.domain == A) and (morphism.codomain == B):
+                premises |= FiniteSet(morphism)
+        for morphism in self.conclusions.keys():
+            if (morphism.domain == A) and (morphism.codomain == B):
+                conclusions |= FiniteSet(morphism)
+
+        return (premises, conclusions)
+
+    def is_subdiagram(self, diagram):
+        """
+        Checks whether ``diagram`` is a subdiagram of ``self``.
+        Diagram `D'` is a subdiagram of `D` if all premises
+        (conclusions) of `D'` are contained in the premises
+        (conclusions) of `D`.  The morphisms contained
+        both in `D'` and `D` should have the same properties for `D'`
+        to be a subdiagram of `D`.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism, Diagram
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> d = Diagram([f, g], {g * f: "unique"})
+        >>> d1 = Diagram([f])
+        >>> d.is_subdiagram(d1)
+        True
+        >>> d1.is_subdiagram(d)
+        False
+        """
+        premises = all((m in self.premises) and
+                       (diagram.premises[m] == self.premises[m])
+                       for m in diagram.premises)
+        if not premises:
+            return False
+
+        conclusions = all((m in self.conclusions) and
+                          (diagram.conclusions[m] == self.conclusions[m])
+                          for m in diagram.conclusions)
+
+        # Premises is surely ``True`` here.
+        return conclusions
+
+    def subdiagram_from_objects(self, objects):
+        """
+        If ``objects`` is a subset of the objects of ``self``, returns
+        a diagram which has as premises all those premises of ``self``
+        which have a domains and codomains in ``objects``, likewise
+        for conclusions.  Properties are preserved.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism, Diagram
+        >>> from sympy import FiniteSet
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> d = Diagram([f, g], {f: "unique", g*f: "veryunique"})
+        >>> d1 = d.subdiagram_from_objects(FiniteSet(A, B))
+        >>> d1 == Diagram([f], {f: "unique"})
+        True
+        """
+        if not objects.is_subset(self.objects):
+            raise ValueError(
+                "Supplied objects should all belong to the diagram.")
+
+        new_premises = {}
+        for morphism, props in self.premises.items():
+            if ((sympify(objects.contains(morphism.domain)) is S.true) and
+                (sympify(objects.contains(morphism.codomain)) is S.true)):
+                new_premises[morphism] = props
+
+        new_conclusions = {}
+        for morphism, props in self.conclusions.items():
+            if ((sympify(objects.contains(morphism.domain)) is S.true) and
+                (sympify(objects.contains(morphism.codomain)) is S.true)):
+                new_conclusions[morphism] = props
+
+        return Diagram(new_premises, new_conclusions)

.venv/lib/python3.13/site-packages/sympy/categories/diagram_drawing.py

@@ -0,0 +1,2580 @@
+r"""
+This module contains the functionality to arrange the nodes of a
+diagram on an abstract grid, and then to produce a graphical
+representation of the grid.
+
+The currently supported back-ends are Xy-pic [Xypic].
+
+Layout Algorithm
+================
+
+This section provides an overview of the algorithms implemented in
+:class:`DiagramGrid` to lay out diagrams.
+
+The first step of the algorithm is the removal composite and identity
+morphisms which do not have properties in the supplied diagram.  The
+premises and conclusions of the diagram are then merged.
+
+The generic layout algorithm begins with the construction of the
+"skeleton" of the diagram.  The skeleton is an undirected graph which
+has the objects of the diagram as vertices and has an (undirected)
+edge between each pair of objects between which there exist morphisms.
+The direction of the morphisms does not matter at this stage.  The
+skeleton also includes an edge between each pair of vertices `A` and
+`C` such that there exists an object `B` which is connected via
+a morphism to `A`, and via a morphism to `C`.
+
+The skeleton constructed in this way has the property that every
+object is a vertex of a triangle formed by three edges of the
+skeleton.  This property lies at the base of the generic layout
+algorithm.
+
+After the skeleton has been constructed, the algorithm lists all
+triangles which can be formed.  Note that some triangles will not have
+all edges corresponding to morphisms which will actually be drawn.
+Triangles which have only one edge or less which will actually be
+drawn are immediately discarded.
+
+The list of triangles is sorted according to the number of edges which
+correspond to morphisms, then the triangle with the least number of such
+edges is selected.  One of such edges is picked and the corresponding
+objects are placed horizontally, on a grid.  This edge is recorded to
+be in the fringe.  The algorithm then finds a "welding" of a triangle
+to the fringe.  A welding is an edge in the fringe where a triangle
+could be attached.  If the algorithm succeeds in finding such a
+welding, it adds to the grid that vertex of the triangle which was not
+yet included in any edge in the fringe and records the two new edges in
+the fringe.  This process continues iteratively until all objects of
+the diagram has been placed or until no more weldings can be found.
+
+An edge is only removed from the fringe when a welding to this edge
+has been found, and there is no room around this edge to place
+another vertex.
+
+When no more weldings can be found, but there are still triangles
+left, the algorithm searches for a possibility of attaching one of the
+remaining triangles to the existing structure by a vertex.  If such a
+possibility is found, the corresponding edge of the found triangle is
+placed in the found space and the iterative process of welding
+triangles restarts.
+
+When logical groups are supplied, each of these groups is laid out
+independently.  Then a diagram is constructed in which groups are
+objects and any two logical groups between which there exist morphisms
+are connected via a morphism.  This diagram is laid out.  Finally,
+the grid which includes all objects of the initial diagram is
+constructed by replacing the cells which contain logical groups with
+the corresponding laid out grids, and by correspondingly expanding the
+rows and columns.
+
+The sequential layout algorithm begins by constructing the
+underlying undirected graph defined by the morphisms obtained after
+simplifying premises and conclusions and merging them (see above).
+The vertex with the minimal degree is then picked up and depth-first
+search is started from it.  All objects which are located at distance
+`n` from the root in the depth-first search tree, are positioned in
+the `n`-th column of the resulting grid.  The sequential layout will
+therefore attempt to lay the objects out along a line.
+
+References
+==========
+
+.. [Xypic] https://xy-pic.sourceforge.net/
+
+"""
+from sympy.categories import (CompositeMorphism, IdentityMorphism,
+                              NamedMorphism, Diagram)
+from sympy.core import Dict, Symbol, default_sort_key
+from sympy.printing.latex import latex
+from sympy.sets import FiniteSet
+from sympy.utilities.iterables import iterable
+from sympy.utilities.decorator import doctest_depends_on
+
+from itertools import chain
+
+
+__doctest_requires__ = {('preview_diagram',): 'pyglet'}
+
+
+class _GrowableGrid:
+    """
+    Holds a growable grid of objects.
+
+    Explanation
+    ===========
+
+    It is possible to append or prepend a row or a column to the grid
+    using the corresponding methods.  Prepending rows or columns has
+    the effect of changing the coordinates of the already existing
+    elements.
+
+    This class currently represents a naive implementation of the
+    functionality with little attempt at optimisation.
+    """
+    def __init__(self, width, height):
+        self._width = width
+        self._height = height
+
+        self._array = [[None for j in range(width)] for i in range(height)]
+
+    @property
+    def width(self):
+        return self._width
+
+    @property
+    def height(self):
+        return self._height
+
+    def __getitem__(self, i_j):
+        """
+        Returns the element located at in the i-th line and j-th
+        column.
+        """
+        i, j = i_j
+        return self._array[i][j]
+
+    def __setitem__(self, i_j, newvalue):
+        """
+        Sets the element located at in the i-th line and j-th
+        column.
+        """
+        i, j = i_j
+        self._array[i][j] = newvalue
+
+    def append_row(self):
+        """
+        Appends an empty row to the grid.
+        """
+        self._height += 1
+        self._array.append([None for j in range(self._width)])
+
+    def append_column(self):
+        """
+        Appends an empty column to the grid.
+        """
+        self._width += 1
+        for i in range(self._height):
+            self._array[i].append(None)
+
+    def prepend_row(self):
+        """
+        Prepends the grid with an empty row.
+        """
+        self._height += 1
+        self._array.insert(0, [None for j in range(self._width)])
+
+    def prepend_column(self):
+        """
+        Prepends the grid with an empty column.
+        """
+        self._width += 1
+        for i in range(self._height):
+            self._array[i].insert(0, None)
+
+
+class DiagramGrid:
+    r"""
+    Constructs and holds the fitting of the diagram into a grid.
+
+    Explanation
+    ===========
+
+    The mission of this class is to analyse the structure of the
+    supplied diagram and to place its objects on a grid such that,
+    when the objects and the morphisms are actually drawn, the diagram
+    would be "readable", in the sense that there will not be many
+    intersections of moprhisms.  This class does not perform any
+    actual drawing.  It does strive nevertheless to offer sufficient
+    metadata to draw a diagram.
+
+    Consider the following simple diagram.
+
+    >>> from sympy.categories import Object, NamedMorphism
+    >>> from sympy.categories import Diagram, DiagramGrid
+    >>> from sympy import pprint
+    >>> A = Object("A")
+    >>> B = Object("B")
+    >>> C = Object("C")
+    >>> f = NamedMorphism(A, B, "f")
+    >>> g = NamedMorphism(B, C, "g")
+    >>> diagram = Diagram([f, g])
+
+    The simplest way to have a diagram laid out is the following:
+
+    >>> grid = DiagramGrid(diagram)
+    >>> (grid.width, grid.height)
+    (2, 2)
+    >>> pprint(grid)
+    A  B
+    <BLANKLINE>
+       C
+
+    Sometimes one sees the diagram as consisting of logical groups.
+    One can advise ``DiagramGrid`` as to such groups by employing the
+    ``groups`` keyword argument.
+
+    Consider the following diagram:
+
+    >>> D = Object("D")
+    >>> f = NamedMorphism(A, B, "f")
+    >>> g = NamedMorphism(B, C, "g")
+    >>> h = NamedMorphism(D, A, "h")
+    >>> k = NamedMorphism(D, B, "k")
+    >>> diagram = Diagram([f, g, h, k])
+
+    Lay it out with generic layout:
+
+    >>> grid = DiagramGrid(diagram)
+    >>> pprint(grid)
+    A  B  D
+    <BLANKLINE>
+       C
+
+    Now, we can group the objects `A` and `D` to have them near one
+    another:
+
+    >>> grid = DiagramGrid(diagram, groups=[[A, D], B, C])
+    >>> pprint(grid)
+    B     C
+    <BLANKLINE>
+    A  D
+
+    Note how the positioning of the other objects changes.
+
+    Further indications can be supplied to the constructor of
+    :class:`DiagramGrid` using keyword arguments.  The currently
+    supported hints are explained in the following paragraphs.
+
+    :class:`DiagramGrid` does not automatically guess which layout
+    would suit the supplied diagram better.  Consider, for example,
+    the following linear diagram:
+
+    >>> E = Object("E")
+    >>> f = NamedMorphism(A, B, "f")
+    >>> g = NamedMorphism(B, C, "g")
+    >>> h = NamedMorphism(C, D, "h")
+    >>> i = NamedMorphism(D, E, "i")
+    >>> diagram = Diagram([f, g, h, i])
+
+    When laid out with the generic layout, it does not get to look
+    linear:
+
+    >>> grid = DiagramGrid(diagram)
+    >>> pprint(grid)
+    A  B
+    <BLANKLINE>
+       C  D
+    <BLANKLINE>
+          E
+
+    To get it laid out in a line, use ``layout="sequential"``:
+
+    >>> grid = DiagramGrid(diagram, layout="sequential")
+    >>> pprint(grid)
+    A  B  C  D  E
+
+    One may sometimes need to transpose the resulting layout.  While
+    this can always be done by hand, :class:`DiagramGrid` provides a
+    hint for that purpose:
+
+    >>> grid = DiagramGrid(diagram, layout="sequential", transpose=True)
+    >>> pprint(grid)
+    A
+    <BLANKLINE>
+    B
+    <BLANKLINE>
+    C
+    <BLANKLINE>
+    D
+    <BLANKLINE>
+    E
+
+    Separate hints can also be provided for each group.  For an
+    example, refer to ``tests/test_drawing.py``, and see the different
+    ways in which the five lemma [FiveLemma] can be laid out.
+
+    See Also
+    ========
+
+    Diagram
+
+    References
+    ==========
+
+    .. [FiveLemma] https://en.wikipedia.org/wiki/Five_lemma
+    """
+    @staticmethod
+    def _simplify_morphisms(morphisms):
+        """
+        Given a dictionary mapping morphisms to their properties,
+        returns a new dictionary in which there are no morphisms which
+        do not have properties, and which are compositions of other
+        morphisms included in the dictionary.  Identities are dropped
+        as well.
+        """
+        newmorphisms = {}
+        for morphism, props in morphisms.items():
+            if isinstance(morphism, CompositeMorphism) and not props:
+                continue
+            elif isinstance(morphism, IdentityMorphism):
+                continue
+            else:
+                newmorphisms[morphism] = props
+        return newmorphisms
+
+    @staticmethod
+    def _merge_premises_conclusions(premises, conclusions):
+        """
+        Given two dictionaries of morphisms and their properties,
+        produces a single dictionary which includes elements from both
+        dictionaries.  If a morphism has some properties in premises
+        and also in conclusions, the properties in conclusions take
+        priority.
+        """
+        return dict(chain(premises.items(), conclusions.items()))
+
+    @staticmethod
+    def _juxtapose_edges(edge1, edge2):
+        """
+        If ``edge1`` and ``edge2`` have precisely one common endpoint,
+        returns an edge which would form a triangle with ``edge1`` and
+        ``edge2``.
+
+        If ``edge1`` and ``edge2`` do not have a common endpoint,
+        returns ``None``.
+
+        If ``edge1`` and ``edge`` are the same edge, returns ``None``.
+        """
+        intersection = edge1 & edge2
+        if len(intersection) != 1:
+            # The edges either have no common points or are equal.
+            return None
+
+        # The edges have a common endpoint.  Extract the different
+        # endpoints and set up the new edge.
+        return (edge1 - intersection) | (edge2 - intersection)
+
+    @staticmethod
+    def _add_edge_append(dictionary, edge, elem):
+        """
+        If ``edge`` is not in ``dictionary``, adds ``edge`` to the
+        dictionary and sets its value to ``[elem]``.  Otherwise
+        appends ``elem`` to the value of existing entry.
+
+        Note that edges are undirected, thus `(A, B) = (B, A)`.
+        """
+        if edge in dictionary:
+            dictionary[edge].append(elem)
+        else:
+            dictionary[edge] = [elem]
+
+    @staticmethod
+    def _build_skeleton(morphisms):
+        """
+        Creates a dictionary which maps edges to corresponding
+        morphisms.  Thus for a morphism `f:A\rightarrow B`, the edge
+        `(A, B)` will be associated with `f`.  This function also adds
+        to the list those edges which are formed by juxtaposition of
+        two edges already in the list.  These new edges are not
+        associated with any morphism and are only added to assure that
+        the diagram can be decomposed into triangles.
+        """
+        edges = {}
+        # Create edges for morphisms.
+        for morphism in morphisms:
+            DiagramGrid._add_edge_append(
+                edges, frozenset([morphism.domain, morphism.codomain]), morphism)
+
+        # Create new edges by juxtaposing existing edges.
+        edges1 = dict(edges)
+        for w in edges1:
+            for v in edges1:
+                wv = DiagramGrid._juxtapose_edges(w, v)
+                if wv and wv not in edges:
+                    edges[wv] = []
+
+        return edges
+
+    @staticmethod
+    def _list_triangles(edges):
+        """
+        Builds the set of triangles formed by the supplied edges.  The
+        triangles are arbitrary and need not be commutative.  A
+        triangle is a set that contains all three of its sides.
+        """
+        triangles = set()
+
+        for w in edges:
+            for v in edges:
+                wv = DiagramGrid._juxtapose_edges(w, v)
+                if wv and wv in edges:
+                    triangles.add(frozenset([w, v, wv]))
+
+        return triangles
+
+    @staticmethod
+    def _drop_redundant_triangles(triangles, skeleton):
+        """
+        Returns a list which contains only those triangles who have
+        morphisms associated with at least two edges.
+        """
+        return [tri for tri in triangles
+                if len([e for e in tri if skeleton[e]]) >= 2]
+
+    @staticmethod
+    def _morphism_length(morphism):
+        """
+        Returns the length of a morphism.  The length of a morphism is
+        the number of components it consists of.  A non-composite
+        morphism is of length 1.
+        """
+        if isinstance(morphism, CompositeMorphism):
+            return len(morphism.components)
+        else:
+            return 1
+
+    @staticmethod
+    def _compute_triangle_min_sizes(triangles, edges):
+        r"""
+        Returns a dictionary mapping triangles to their minimal sizes.
+        The minimal size of a triangle is the sum of maximal lengths
+        of morphisms associated to the sides of the triangle.  The
+        length of a morphism is the number of components it consists
+        of.  A non-composite morphism is of length 1.
+
+        Sorting triangles by this metric attempts to address two
+        aspects of layout.  For triangles with only simple morphisms
+        in the edge, this assures that triangles with all three edges
+        visible will get typeset after triangles with less visible
+        edges, which sometimes minimizes the necessity in diagonal
+        arrows.  For triangles with composite morphisms in the edges,
+        this assures that objects connected with shorter morphisms
+        will be laid out first, resulting the visual proximity of
+        those objects which are connected by shorter morphisms.
+        """
+        triangle_sizes = {}
+        for triangle in triangles:
+            size = 0
+            for e in triangle:
+                morphisms = edges[e]
+                if morphisms:
+                    size += max(DiagramGrid._morphism_length(m)
+                                for m in morphisms)
+            triangle_sizes[triangle] = size
+        return triangle_sizes
+
+    @staticmethod
+    def _triangle_objects(triangle):
+        """
+        Given a triangle, returns the objects included in it.
+        """
+        # A triangle is a frozenset of three two-element frozensets
+        # (the edges).  This chains the three edges together and
+        # creates a frozenset from the iterator, thus producing a
+        # frozenset of objects of the triangle.
+        return frozenset(chain(*tuple(triangle)))
+
+    @staticmethod
+    def _other_vertex(triangle, edge):
+        """
+        Given a triangle and an edge of it, returns the vertex which
+        opposes the edge.
+        """
+        # This gets the set of objects of the triangle and then
+        # subtracts the set of objects employed in ``edge`` to get the
+        # vertex opposite to ``edge``.
+        return list(DiagramGrid._triangle_objects(triangle) - set(edge))[0]
+
+    @staticmethod
+    def _empty_point(pt, grid):
+        """
+        Checks if the cell at coordinates ``pt`` is either empty or
+        out of the bounds of the grid.
+        """
+        if (pt[0] < 0) or (pt[1] < 0) or \
+           (pt[0] >= grid.height) or (pt[1] >= grid.width):
+            return True
+        return grid[pt] is None
+
+    @staticmethod
+    def _put_object(coords, obj, grid, fringe):
+        """
+        Places an object at the coordinate ``cords`` in ``grid``,
+        growing the grid and updating ``fringe``, if necessary.
+        Returns (0, 0) if no row or column has been prepended, (1, 0)
+        if a row was prepended, (0, 1) if a column was prepended and
+        (1, 1) if both a column and a row were prepended.
+        """
+        (i, j) = coords
+        offset = (0, 0)
+        if i == -1:
+            grid.prepend_row()
+            i = 0
+            offset = (1, 0)
+            for k in range(len(fringe)):
+                ((i1, j1), (i2, j2)) = fringe[k]
+                fringe[k] = ((i1 + 1, j1), (i2 + 1, j2))
+        elif i == grid.height:
+            grid.append_row()
+
+        if j == -1:
+            j = 0
+            offset = (offset[0], 1)
+            grid.prepend_column()
+            for k in range(len(fringe)):
+                ((i1, j1), (i2, j2)) = fringe[k]
+                fringe[k] = ((i1, j1 + 1), (i2, j2 + 1))
+        elif j == grid.width:
+            grid.append_column()
+
+        grid[i, j] = obj
+        return offset
+
+    @staticmethod
+    def _choose_target_cell(pt1, pt2, edge, obj, skeleton, grid):
+        """
+        Given two points, ``pt1`` and ``pt2``, and the welding edge
+        ``edge``, chooses one of the two points to place the opposing
+        vertex ``obj`` of the triangle.  If neither of this points
+        fits, returns ``None``.
+        """
+        pt1_empty = DiagramGrid._empty_point(pt1, grid)
+        pt2_empty = DiagramGrid._empty_point(pt2, grid)
+
+        if pt1_empty and pt2_empty:
+            # Both cells are empty.  Of these two, choose that cell
+            # which will assure that a visible edge of the triangle
+            # will be drawn perpendicularly to the current welding
+            # edge.
+
+            A = grid[edge[0]]
+
+            if skeleton.get(frozenset([A, obj])):
+                return pt1
+            else:
+                return pt2
+        if pt1_empty:
+            return pt1
+        elif pt2_empty:
+            return pt2
+        else:
+            return None
+
+    @staticmethod
+    def _find_triangle_to_weld(triangles, fringe, grid):
+        """
+        Finds, if possible, a triangle and an edge in the ``fringe`` to
+        which the triangle could be attached.  Returns the tuple
+        containing the triangle and the index of the corresponding
+        edge in the ``fringe``.
+
+        This function relies on the fact that objects are unique in
+        the diagram.
+        """
+        for triangle in triangles:
+            for (a, b) in fringe:
+                if frozenset([grid[a], grid[b]]) in triangle:
+                    return (triangle, (a, b))
+        return None
+
+    @staticmethod
+    def _weld_triangle(tri, welding_edge, fringe, grid, skeleton):
+        """
+        If possible, welds the triangle ``tri`` to ``fringe`` and
+        returns ``False``.  If this method encounters a degenerate
+        situation in the fringe and corrects it such that a restart of
+        the search is required, it returns ``True`` (which means that
+        a restart in finding triangle weldings is required).
+
+        A degenerate situation is a situation when an edge listed in
+        the fringe does not belong to the visual boundary of the
+        diagram.
+        """
+        a, b = welding_edge
+        target_cell = None
+
+        obj = DiagramGrid._other_vertex(tri, (grid[a], grid[b]))
+
+        # We now have a triangle and an edge where it can be welded to
+        # the fringe.  Decide where to place the other vertex of the
+        # triangle and check for degenerate situations en route.
+
+        if (abs(a[0] - b[0]) == 1) and (abs(a[1] - b[1]) == 1):
+            # A diagonal edge.
+            target_cell = (a[0], b[1])
+            if grid[target_cell]:
+                # That cell is already occupied.
+                target_cell = (b[0], a[1])
+
+                if grid[target_cell]:
+                    # Degenerate situation, this edge is not
+                    # on the actual fringe.  Correct the
+                    # fringe and go on.
+                    fringe.remove((a, b))
+                    return True
+        elif a[0] == b[0]:
+            # A horizontal edge.  We first attempt to build the
+            # triangle in the downward direction.
+
+            down_left = a[0] + 1, a[1]
+            down_right = a[0] + 1, b[1]
+
+            target_cell = DiagramGrid._choose_target_cell(
+                down_left, down_right, (a, b), obj, skeleton, grid)
+
+            if not target_cell:
+                # No room below this edge.  Check above.
+                up_left = a[0] - 1, a[1]
+                up_right = a[0] - 1, b[1]
+
+                target_cell = DiagramGrid._choose_target_cell(
+                    up_left, up_right, (a, b), obj, skeleton, grid)
+
+                if not target_cell:
+                    # This edge is not in the fringe, remove it
+                    # and restart.
+                    fringe.remove((a, b))
+                    return True
+        elif a[1] == b[1]:
+            # A vertical edge.  We will attempt to place the other
+            # vertex of the triangle to the right of this edge.
+            right_up = a[0], a[1] + 1
+            right_down = b[0], a[1] + 1
+
+            target_cell = DiagramGrid._choose_target_cell(
+                right_up, right_down, (a, b), obj, skeleton, grid)
+
+            if not target_cell:
+                # No room to the left.  See what's to the right.
+                left_up = a[0], a[1] - 1
+                left_down = b[0], a[1] - 1
+
+                target_cell = DiagramGrid._choose_target_cell(
+                    left_up, left_down, (a, b), obj, skeleton, grid)
+
+                if not target_cell:
+                    # This edge is not in the fringe, remove it
+                    # and restart.
+                    fringe.remove((a, b))
+                    return True
+
+        # We now know where to place the other vertex of the
+        # triangle.
+        offset = DiagramGrid._put_object(target_cell, obj, grid, fringe)
+
+        # Take care of the displacement of coordinates if a row or
+        # a column was prepended.
+        target_cell = (target_cell[0] + offset[0],
+                       target_cell[1] + offset[1])
+        a = (a[0] + offset[0], a[1] + offset[1])
+        b = (b[0] + offset[0], b[1] + offset[1])
+
+        fringe.extend([(a, target_cell), (b, target_cell)])
+
+        # No restart is required.
+        return False
+
+    @staticmethod
+    def _triangle_key(tri, triangle_sizes):
+        """
+        Returns a key for the supplied triangle.  It should be the
+        same independently of the hash randomisation.
+        """
+        objects = sorted(
+            DiagramGrid._triangle_objects(tri), key=default_sort_key)
+        return (triangle_sizes[tri], default_sort_key(objects))
+
+    @staticmethod
+    def _pick_root_edge(tri, skeleton):
+        """
+        For a given triangle always picks the same root edge.  The
+        root edge is the edge that will be placed first on the grid.
+        """
+        candidates = [sorted(e, key=default_sort_key)
+                      for e in tri if skeleton[e]]
+        sorted_candidates = sorted(candidates, key=default_sort_key)
+        # Don't forget to assure the proper ordering of the vertices
+        # in this edge.
+        return tuple(sorted(sorted_candidates[0], key=default_sort_key))
+
+    @staticmethod
+    def _drop_irrelevant_triangles(triangles, placed_objects):
+        """
+        Returns only those triangles whose set of objects is not
+        completely included in ``placed_objects``.
+        """
+        return [tri for tri in triangles if not placed_objects.issuperset(
+            DiagramGrid._triangle_objects(tri))]
+
+    @staticmethod
+    def _grow_pseudopod(triangles, fringe, grid, skeleton, placed_objects):
+        """
+        Starting from an object in the existing structure on the ``grid``,
+        adds an edge to which a triangle from ``triangles`` could be
+        welded.  If this method has found a way to do so, it returns
+        the object it has just added.
+
+        This method should be applied when ``_weld_triangle`` cannot
+        find weldings any more.
+        """
+        for i in range(grid.height):
+            for j in range(grid.width):
+                obj = grid[i, j]
+                if not obj:
+                    continue
+
+                # Here we need to choose a triangle which has only
+                # ``obj`` in common with the existing structure.  The
+                # situations when this is not possible should be
+                # handled elsewhere.
+
+                def good_triangle(tri):
+                    objs = DiagramGrid._triangle_objects(tri)
+                    return obj in objs and \
+                        placed_objects & (objs - {obj}) == set()
+
+                tris = [tri for tri in triangles if good_triangle(tri)]
+                if not tris:
+                    # This object is not interesting.
+                    continue
+
+                # Pick the "simplest" of the triangles which could be
+                # attached.  Remember that the list of triangles is
+                # sorted according to their "simplicity" (see
+                # _compute_triangle_min_sizes for the metric).
+                #
+                # Note that ``tris`` are sequentially built from
+                # ``triangles``, so we don't have to worry about hash
+                # randomisation.
+                tri = tris[0]
+
+                # We have found a triangle which could be attached to
+                # the existing structure by a vertex.
+
+                candidates = sorted([e for e in tri if skeleton[e]],
+                                    key=lambda e: FiniteSet(*e).sort_key())
+                edges = [e for e in candidates if obj in e]
+
+                # Note that a meaningful edge (i.e., and edge that is
+                # associated with a morphism) containing ``obj``
+                # always exists.  That's because all triangles are
+                # guaranteed to have at least two meaningful edges.
+                # See _drop_redundant_triangles.
+
+                # Get the object at the other end of the edge.
+                edge = edges[0]
+                other_obj = tuple(edge - frozenset([obj]))[0]
+
+                # Now check for free directions.  When checking for
+                # free directions, prefer the horizontal and vertical
+                # directions.
+                neighbours = [(i - 1, j), (i, j + 1), (i + 1, j), (i, j - 1),
+                              (i - 1, j - 1), (i - 1, j + 1), (i + 1, j - 1), (i + 1, j + 1)]
+
+                for pt in neighbours:
+                    if DiagramGrid._empty_point(pt, grid):
+                        # We have a found a place to grow the
+                        # pseudopod into.
+                        offset = DiagramGrid._put_object(
+                            pt, other_obj, grid, fringe)
+
+                        i += offset[0]
+                        j += offset[1]
+                        pt = (pt[0] + offset[0], pt[1] + offset[1])
+                        fringe.append(((i, j), pt))
+
+                        return other_obj
+
+        # This diagram is actually cooler that I can handle.  Fail cowardly.
+        return None
+
+    @staticmethod
+    def _handle_groups(diagram, groups, merged_morphisms, hints):
+        """
+        Given the slightly preprocessed morphisms of the diagram,
+        produces a grid laid out according to ``groups``.
+
+        If a group has hints, it is laid out with those hints only,
+        without any influence from ``hints``.  Otherwise, it is laid
+        out with ``hints``.
+        """
+        def lay_out_group(group, local_hints):
+            """
+            If ``group`` is a set of objects, uses a ``DiagramGrid``
+            to lay it out and returns the grid.  Otherwise returns the
+            object (i.e., ``group``).  If ``local_hints`` is not
+            empty, it is supplied to ``DiagramGrid`` as the dictionary
+            of hints.  Otherwise, the ``hints`` argument of
+            ``_handle_groups`` is used.
+            """
+            if isinstance(group, FiniteSet):
+                # Set up the corresponding object-to-group
+                # mappings.
+                for obj in group:
+                    obj_groups[obj] = group
+
+                # Lay out the current group.
+                if local_hints:
+                    groups_grids[group] = DiagramGrid(
+                        diagram.subdiagram_from_objects(group), **local_hints)
+                else:
+                    groups_grids[group] = DiagramGrid(
+                        diagram.subdiagram_from_objects(group), **hints)
+            else:
+                obj_groups[group] = group
+
+        def group_to_finiteset(group):
+            """
+            Converts ``group`` to a :class:``FiniteSet`` if it is an
+            iterable.
+            """
+            if iterable(group):
+                return FiniteSet(*group)
+            else:
+                return group
+
+        obj_groups = {}
+        groups_grids = {}
+
+        # We would like to support various containers to represent
+        # groups.  To achieve that, before laying each group out, it
+        # should be converted to a FiniteSet, because that is what the
+        # following code expects.
+
+        if isinstance(groups, (dict, Dict)):
+            finiteset_groups = {}
+            for group, local_hints in groups.items():
+                finiteset_group = group_to_finiteset(group)
+                finiteset_groups[finiteset_group] = local_hints
+                lay_out_group(group, local_hints)
+            groups = finiteset_groups
+        else:
+            finiteset_groups = []
+            for group in groups:
+                finiteset_group = group_to_finiteset(group)
+                finiteset_groups.append(finiteset_group)
+                lay_out_group(finiteset_group, None)
+            groups = finiteset_groups
+
+        new_morphisms = []
+        for morphism in merged_morphisms:
+            dom = obj_groups[morphism.domain]
+            cod = obj_groups[morphism.codomain]
+            # Note that we are not really interested in morphisms
+            # which do not employ two different groups, because
+            # these do not influence the layout.
+            if dom != cod:
+                # These are essentially unnamed morphisms; they are
+                # not going to mess in the final layout.  By giving
+                # them the same names, we avoid unnecessary
+                # duplicates.
+                new_morphisms.append(NamedMorphism(dom, cod, "dummy"))
+
+        # Lay out the new diagram.  Since these are dummy morphisms,
+        # properties and conclusions are irrelevant.
+        top_grid = DiagramGrid(Diagram(new_morphisms))
+
+        # We now have to substitute the groups with the corresponding
+        # grids, laid out at the beginning of this function.  Compute
+        # the size of each row and column in the grid, so that all
+        # nested grids fit.
+
+        def group_size(group):
+            """
+            For the supplied group (or object, eventually), returns
+            the size of the cell that will hold this group (object).
+            """
+            if group in groups_grids:
+                grid = groups_grids[group]
+                return (grid.height, grid.width)
+            else:
+                return (1, 1)
+
+        row_heights = [max(group_size(top_grid[i, j])[0]
+                           for j in range(top_grid.width))
+                       for i in range(top_grid.height)]
+
+        column_widths = [max(group_size(top_grid[i, j])[1]
+                             for i in range(top_grid.height))
+                         for j in range(top_grid.width)]
+
+        grid = _GrowableGrid(sum(column_widths), sum(row_heights))
+
+        real_row = 0
+        real_column = 0
+        for logical_row in range(top_grid.height):
+            for logical_column in range(top_grid.width):
+                obj = top_grid[logical_row, logical_column]
+
+                if obj in groups_grids:
+                    # This is a group.  Copy the corresponding grid in
+                    # place.
+                    local_grid = groups_grids[obj]
+                    for i in range(local_grid.height):
+                        for j in range(local_grid.width):
+                            grid[real_row + i,
+                                real_column + j] = local_grid[i, j]
+                else:
+                    # This is an object.  Just put it there.
+                    grid[real_row, real_column] = obj
+
+                real_column += column_widths[logical_column]
+            real_column = 0
+            real_row += row_heights[logical_row]
+
+        return grid
+
+    @staticmethod
+    def _generic_layout(diagram, merged_morphisms):
+        """
+        Produces the generic layout for the supplied diagram.
+        """
+        all_objects = set(diagram.objects)
+        if len(all_objects) == 1:
+            # There only one object in the diagram, just put in on 1x1
+            # grid.
+            grid = _GrowableGrid(1, 1)
+            grid[0, 0] = tuple(all_objects)[0]
+            return grid
+
+        skeleton = DiagramGrid._build_skeleton(merged_morphisms)
+
+        grid = _GrowableGrid(2, 1)
+
+        if len(skeleton) == 1:
+            # This diagram contains only one morphism.  Draw it
+            # horizontally.
+            objects = sorted(all_objects, key=default_sort_key)
+            grid[0, 0] = objects[0]
+            grid[0, 1] = objects[1]
+
+            return grid
+
+        triangles = DiagramGrid._list_triangles(skeleton)
+        triangles = DiagramGrid._drop_redundant_triangles(triangles, skeleton)
+        triangle_sizes = DiagramGrid._compute_triangle_min_sizes(
+            triangles, skeleton)
+
+        triangles = sorted(triangles, key=lambda tri:
+                           DiagramGrid._triangle_key(tri, triangle_sizes))
+
+        # Place the first edge on the grid.
+        root_edge = DiagramGrid._pick_root_edge(triangles[0], skeleton)
+        grid[0, 0], grid[0, 1] = root_edge
+        fringe = [((0, 0), (0, 1))]
+
+        # Record which objects we now have on the grid.
+        placed_objects = set(root_edge)
+
+        while placed_objects != all_objects:
+            welding = DiagramGrid._find_triangle_to_weld(
+                triangles, fringe, grid)
+
+            if welding:
+                (triangle, welding_edge) = welding
+
+                restart_required = DiagramGrid._weld_triangle(
+                    triangle, welding_edge, fringe, grid, skeleton)
+                if restart_required:
+                    continue
+
+                placed_objects.update(
+                    DiagramGrid._triangle_objects(triangle))
+            else:
+                # No more weldings found.  Try to attach triangles by
+                # vertices.
+                new_obj = DiagramGrid._grow_pseudopod(
+                    triangles, fringe, grid, skeleton, placed_objects)
+
+                if not new_obj:
+                    # No more triangles can be attached, not even by
+                    # the edge.  We will set up a new diagram out of
+                    # what has been left, laid it out independently,
+                    # and then attach it to this one.
+
+                    remaining_objects = all_objects - placed_objects
+
+                    remaining_diagram = diagram.subdiagram_from_objects(
+                        FiniteSet(*remaining_objects))
+                    remaining_grid = DiagramGrid(remaining_diagram)
+
+                    # Now, let's glue ``remaining_grid`` to ``grid``.
+                    final_width = grid.width + remaining_grid.width
+                    final_height = max(grid.height, remaining_grid.height)
+                    final_grid = _GrowableGrid(final_width, final_height)
+
+                    for i in range(grid.width):
+                        for j in range(grid.height):
+                            final_grid[i, j] = grid[i, j]
+
+                    start_j = grid.width
+                    for i in range(remaining_grid.height):
+                        for j in range(remaining_grid.width):
+                            final_grid[i, start_j + j] = remaining_grid[i, j]
+
+                    return final_grid
+
+                placed_objects.add(new_obj)
+
+            triangles = DiagramGrid._drop_irrelevant_triangles(
+                triangles, placed_objects)
+
+        return grid
+
+    @staticmethod
+    def _get_undirected_graph(objects, merged_morphisms):
+        """
+        Given the objects and the relevant morphisms of a diagram,
+        returns the adjacency lists of the underlying undirected
+        graph.
+        """
+        adjlists = {obj: [] for obj in objects}
+
+        for morphism in merged_morphisms:
+            adjlists[morphism.domain].append(morphism.codomain)
+            adjlists[morphism.codomain].append(morphism.domain)
+
+        # Assure that the objects in the adjacency list are always in
+        # the same order.
+        for obj in adjlists.keys():
+            adjlists[obj].sort(key=default_sort_key)
+
+        return adjlists
+
+    @staticmethod
+    def _sequential_layout(diagram, merged_morphisms):
+        r"""
+        Lays out the diagram in "sequential" layout.  This method
+        will attempt to produce a result as close to a line as
+        possible.  For linear diagrams, the result will actually be a
+        line.
+        """
+        objects = diagram.objects
+        sorted_objects = sorted(objects, key=default_sort_key)
+
+        # Set up the adjacency lists of the underlying undirected
+        # graph of ``merged_morphisms``.
+        adjlists = DiagramGrid._get_undirected_graph(objects, merged_morphisms)
+
+        root = min(sorted_objects, key=lambda x: len(adjlists[x]))
+        grid = _GrowableGrid(1, 1)
+        grid[0, 0] = root
+
+        placed_objects = {root}
+
+        def place_objects(pt, placed_objects):
+            """
+            Does depth-first search in the underlying graph of the
+            diagram and places the objects en route.
+            """
+            # We will start placing new objects from here.
+            new_pt = (pt[0], pt[1] + 1)
+
+            for adjacent_obj in adjlists[grid[pt]]:
+                if adjacent_obj in placed_objects:
+                    # This object has already been placed.
+                    continue
+
+                DiagramGrid._put_object(new_pt, adjacent_obj, grid, [])
+                placed_objects.add(adjacent_obj)
+                placed_objects.update(place_objects(new_pt, placed_objects))
+
+                new_pt = (new_pt[0] + 1, new_pt[1])
+
+            return placed_objects
+
+        place_objects((0, 0), placed_objects)
+
+        return grid
+
+    @staticmethod
+    def _drop_inessential_morphisms(merged_morphisms):
+        r"""
+        Removes those morphisms which should appear in the diagram,
+        but which have no relevance to object layout.
+
+        Currently this removes "loop" morphisms: the non-identity
+        morphisms with the same domains and codomains.
+        """
+        morphisms = [m for m in merged_morphisms if m.domain != m.codomain]
+        return morphisms
+
+    @staticmethod
+    def _get_connected_components(objects, merged_morphisms):
+        """
+        Given a container of morphisms, returns a list of connected
+        components formed by these morphisms.  A connected component
+        is represented by a diagram consisting of the corresponding
+        morphisms.
+        """
+        component_index = {}
+        for o in objects:
+            component_index[o] = None
+
+        # Get the underlying undirected graph of the diagram.
+        adjlist = DiagramGrid._get_undirected_graph(objects, merged_morphisms)
+
+        def traverse_component(object, current_index):
+            """
+            Does a depth-first search traversal of the component
+            containing ``object``.
+            """
+            component_index[object] = current_index
+            for o in adjlist[object]:
+                if component_index[o] is None:
+                    traverse_component(o, current_index)
+
+        # Traverse all components.
+        current_index = 0
+        for o in adjlist:
+            if component_index[o] is None:
+                traverse_component(o, current_index)
+                current_index += 1
+
+        # List the objects of the components.
+        component_objects = [[] for i in range(current_index)]
+        for o, idx in component_index.items():
+            component_objects[idx].append(o)
+
+        # Finally, list the morphisms belonging to each component.
+        #
+        # Note: If some objects are isolated, they will not get any
+        # morphisms at this stage, and since the layout algorithm
+        # relies, we are essentially going to lose this object.
+        # Therefore, check if there are isolated objects and, for each
+        # of them, provide the trivial identity morphism.  It will get
+        # discarded later, but the object will be there.
+
+        component_morphisms = []
+        for component in component_objects:
+            current_morphisms = {}
+            for m in merged_morphisms:
+                if (m.domain in component) and (m.codomain in component):
+                    current_morphisms[m] = merged_morphisms[m]
+
+            if len(component) == 1:
+                # Let's add an identity morphism, for the sake of
+                # surely having morphisms in this component.
+                current_morphisms[IdentityMorphism(component[0])] = FiniteSet()
+
+            component_morphisms.append(Diagram(current_morphisms))
+
+        return component_morphisms
+
+    def __init__(self, diagram, groups=None, **hints):
+        premises = DiagramGrid._simplify_morphisms(diagram.premises)
+        conclusions = DiagramGrid._simplify_morphisms(diagram.conclusions)
+        all_merged_morphisms = DiagramGrid._merge_premises_conclusions(
+            premises, conclusions)
+        merged_morphisms = DiagramGrid._drop_inessential_morphisms(
+            all_merged_morphisms)
+
+        # Store the merged morphisms for later use.
+        self._morphisms = all_merged_morphisms
+
+        components = DiagramGrid._get_connected_components(
+            diagram.objects, all_merged_morphisms)
+
+        if groups and (groups != diagram.objects):
+            # Lay out the diagram according to the groups.
+            self._grid = DiagramGrid._handle_groups(
+                diagram, groups, merged_morphisms, hints)
+        elif len(components) > 1:
+            # Note that we check for connectedness _before_ checking
+            # the layout hints because the layout strategies don't
+            # know how to deal with disconnected diagrams.
+
+            # The diagram is disconnected.  Lay out the components
+            # independently.
+            grids = []
+
+            # Sort the components to eventually get the grids arranged
+            # in a fixed, hash-independent order.
+            components = sorted(components, key=default_sort_key)
+
+            for component in components:
+                grid = DiagramGrid(component, **hints)
+                grids.append(grid)
+
+            # Throw the grids together, in a line.
+            total_width = sum(g.width for g in grids)
+            total_height = max(g.height for g in grids)
+
+            grid = _GrowableGrid(total_width, total_height)
+            start_j = 0
+            for g in grids:
+                for i in range(g.height):
+                    for j in range(g.width):
+                        grid[i, start_j + j] = g[i, j]
+
+                start_j += g.width
+
+            self._grid = grid
+        elif "layout" in hints:
+            if hints["layout"] == "sequential":
+                self._grid = DiagramGrid._sequential_layout(
+                    diagram, merged_morphisms)
+        else:
+            self._grid = DiagramGrid._generic_layout(diagram, merged_morphisms)
+
+        if hints.get("transpose"):
+            # Transpose the resulting grid.
+            grid = _GrowableGrid(self._grid.height, self._grid.width)
+            for i in range(self._grid.height):
+                for j in range(self._grid.width):
+                    grid[j, i] = self._grid[i, j]
+            self._grid = grid
+
+    @property
+    def width(self):
+        """
+        Returns the number of columns in this diagram layout.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism
+        >>> from sympy.categories import Diagram, DiagramGrid
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> diagram = Diagram([f, g])
+        >>> grid = DiagramGrid(diagram)
+        >>> grid.width
+        2
+
+        """
+        return self._grid.width
+
+    @property
+    def height(self):
+        """
+        Returns the number of rows in this diagram layout.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism
+        >>> from sympy.categories import Diagram, DiagramGrid
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> diagram = Diagram([f, g])
+        >>> grid = DiagramGrid(diagram)
+        >>> grid.height
+        2
+
+        """
+        return self._grid.height
+
+    def __getitem__(self, i_j):
+        """
+        Returns the object placed in the row ``i`` and column ``j``.
+        The indices are 0-based.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism
+        >>> from sympy.categories import Diagram, DiagramGrid
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> diagram = Diagram([f, g])
+        >>> grid = DiagramGrid(diagram)
+        >>> (grid[0, 0], grid[0, 1])
+        (Object("A"), Object("B"))
+        >>> (grid[1, 0], grid[1, 1])
+        (None, Object("C"))
+
+        """
+        i, j = i_j
+        return self._grid[i, j]
+
+    @property
+    def morphisms(self):
+        """
+        Returns those morphisms (and their properties) which are
+        sufficiently meaningful to be drawn.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism
+        >>> from sympy.categories import Diagram, DiagramGrid
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> diagram = Diagram([f, g])
+        >>> grid = DiagramGrid(diagram)
+        >>> grid.morphisms
+        {NamedMorphism(Object("A"), Object("B"), "f"): EmptySet,
+        NamedMorphism(Object("B"), Object("C"), "g"): EmptySet}
+
+        """
+        return self._morphisms
+
+    def __str__(self):
+        """
+        Produces a string representation of this class.
+
+        This method returns a string representation of the underlying
+        list of lists of objects.
+
+        Examples
+        ========
+
+        >>> from sympy.categories import Object, NamedMorphism
+        >>> from sympy.categories import Diagram, DiagramGrid
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> diagram = Diagram([f, g])
+        >>> grid = DiagramGrid(diagram)
+        >>> print(grid)
+        [[Object("A"), Object("B")],
+        [None, Object("C")]]
+
+        """
+        return repr(self._grid._array)
+
+
+class ArrowStringDescription:
+    r"""
+    Stores the information necessary for producing an Xy-pic
+    description of an arrow.
+
+    The principal goal of this class is to abstract away the string
+    representation of an arrow and to also provide the functionality
+    to produce the actual Xy-pic string.
+
+    ``unit`` sets the unit which will be used to specify the amount of
+    curving and other distances.  ``horizontal_direction`` should be a
+    string of ``"r"`` or ``"l"`` specifying the horizontal offset of the
+    target cell of the arrow relatively to the current one.
+    ``vertical_direction`` should  specify the vertical offset using a
+    series of either ``"d"`` or ``"u"``.  ``label_position`` should be
+    either ``"^"``, ``"_"``,  or ``"|"`` to specify that the label should
+    be positioned above the arrow, below the arrow or just over the arrow,
+    in a break.  Note that the notions "above" and "below" are relative
+    to arrow direction.  ``label`` stores the morphism label.
+
+    This works as follows (disregard the yet unexplained arguments):
+
+    >>> from sympy.categories.diagram_drawing import ArrowStringDescription
+    >>> astr = ArrowStringDescription(
+    ... unit="mm", curving=None, curving_amount=None,
+    ... looping_start=None, looping_end=None, horizontal_direction="d",
+    ... vertical_direction="r", label_position="_", label="f")
+    >>> print(str(astr))
+    \ar[dr]_{f}
+
+    ``curving`` should be one of ``"^"``, ``"_"`` to specify in which
+    direction the arrow is going to curve. ``curving_amount`` is a number
+    describing how many ``unit``'s the morphism is going to curve:
+
+    >>> astr = ArrowStringDescription(
+    ... unit="mm", curving="^", curving_amount=12,
+    ... looping_start=None, looping_end=None, horizontal_direction="d",
+    ... vertical_direction="r", label_position="_", label="f")
+    >>> print(str(astr))
+    \ar@/^12mm/[dr]_{f}
+
+    ``looping_start`` and ``looping_end`` are currently only used for
+    loop morphisms, those which have the same domain and codomain.
+    These two attributes should store a valid Xy-pic direction and
+    specify, correspondingly, the direction the arrow gets out into
+    and the direction the arrow gets back from:
+
+    >>> astr = ArrowStringDescription(
+    ... unit="mm", curving=None, curving_amount=None,
+    ... looping_start="u", looping_end="l", horizontal_direction="",
+    ... vertical_direction="", label_position="_", label="f")
+    >>> print(str(astr))
+    \ar@(u,l)[]_{f}
+
+    ``label_displacement`` controls how far the arrow label is from
+    the ends of the arrow.  For example, to position the arrow label
+    near the arrow head, use ">":
+
+    >>> astr = ArrowStringDescription(
+    ... unit="mm", curving="^", curving_amount=12,
+    ... looping_start=None, looping_end=None, horizontal_direction="d",
+    ... vertical_direction="r", label_position="_", label="f")
+    >>> astr.label_displacement = ">"
+    >>> print(str(astr))
+    \ar@/^12mm/[dr]_>{f}
+
+    Finally, ``arrow_style`` is used to specify the arrow style.  To
+    get a dashed arrow, for example, use "{-->}" as arrow style:
+
+    >>> astr = ArrowStringDescription(
+    ... unit="mm", curving="^", curving_amount=12,
+    ... looping_start=None, looping_end=None, horizontal_direction="d",
+    ... vertical_direction="r", label_position="_", label="f")
+    >>> astr.arrow_style = "{-->}"
+    >>> print(str(astr))
+    \ar@/^12mm/@{-->}[dr]_{f}
+
+    Notes
+    =====
+
+    Instances of :class:`ArrowStringDescription` will be constructed
+    by :class:`XypicDiagramDrawer` and provided for further use in
+    formatters.  The user is not expected to construct instances of
+    :class:`ArrowStringDescription` themselves.
+
+    To be able to properly utilise this class, the reader is encouraged
+    to checkout the Xy-pic user guide, available at [Xypic].
+
+    See Also
+    ========
+
+    XypicDiagramDrawer
+
+    References
+    ==========
+
+    .. [Xypic] https://xy-pic.sourceforge.net/
+    """
+    def __init__(self, unit, curving, curving_amount, looping_start,
+                 looping_end, horizontal_direction, vertical_direction,
+                 label_position, label):
+        self.unit = unit
+        self.curving = curving
+        self.curving_amount = curving_amount
+        self.looping_start = looping_start
+        self.looping_end = looping_end
+        self.horizontal_direction = horizontal_direction
+        self.vertical_direction = vertical_direction
+        self.label_position = label_position
+        self.label = label
+
+        self.label_displacement = ""
+        self.arrow_style = ""
+
+        # This flag shows that the position of the label of this
+        # morphism was set while typesetting a curved morphism and
+        # should not be modified later.
+        self.forced_label_position = False
+
+    def __str__(self):
+        if self.curving:
+            curving_str = "@/%s%d%s/" % (self.curving, self.curving_amount,
+                                         self.unit)
+        else:
+            curving_str = ""
+
+        if self.looping_start and self.looping_end:
+            looping_str = "@(%s,%s)" % (self.looping_start, self.looping_end)
+        else:
+            looping_str = ""
+
+        if self.arrow_style:
+
+            style_str = "@" + self.arrow_style
+        else:
+            style_str = ""
+
+        return "\\ar%s%s%s[%s%s]%s%s{%s}" % \
+               (curving_str, looping_str, style_str, self.horizontal_direction,
+                self.vertical_direction, self.label_position,
+                self.label_displacement, self.label)
+
+
+class XypicDiagramDrawer:
+    r"""
+    Given a :class:`~.Diagram` and the corresponding
+    :class:`DiagramGrid`, produces the Xy-pic representation of the
+    diagram.
+
+    The most important method in this class is ``draw``.  Consider the
+    following triangle diagram:
+
+    >>> from sympy.categories import Object, NamedMorphism, Diagram
+    >>> from sympy.categories import DiagramGrid, XypicDiagramDrawer
+    >>> A = Object("A")
+    >>> B = Object("B")
+    >>> C = Object("C")
+    >>> f = NamedMorphism(A, B, "f")
+    >>> g = NamedMorphism(B, C, "g")
+    >>> diagram = Diagram([f, g], {g * f: "unique"})
+
+    To draw this diagram, its objects need to be laid out with a
+    :class:`DiagramGrid`::
+
+    >>> grid = DiagramGrid(diagram)
+
+    Finally, the drawing:
+
+    >>> drawer = XypicDiagramDrawer()
+    >>> print(drawer.draw(diagram, grid))
+    \xymatrix{
+    A \ar[d]_{g\circ f} \ar[r]^{f} & B \ar[ld]^{g} \\
+    C &
+    }
+
+    For further details see the docstring of this method.
+
+    To control the appearance of the arrows, formatters are used.  The
+    dictionary ``arrow_formatters`` maps morphisms to formatter
+    functions.  A formatter is accepts an
+    :class:`ArrowStringDescription` and is allowed to modify any of
+    the arrow properties exposed thereby.  For example, to have all
+    morphisms with the property ``unique`` appear as dashed arrows,
+    and to have their names prepended with `\exists !`, the following
+    should be done:
+
+    >>> def formatter(astr):
+    ...   astr.label = r"\exists !" + astr.label
+    ...   astr.arrow_style = "{-->}"
+    >>> drawer.arrow_formatters["unique"] = formatter
+    >>> print(drawer.draw(diagram, grid))
+    \xymatrix{
+    A \ar@{-->}[d]_{\exists !g\circ f} \ar[r]^{f} & B \ar[ld]^{g} \\
+    C &
+    }
+
+    To modify the appearance of all arrows in the diagram, set
+    ``default_arrow_formatter``.  For example, to place all morphism
+    labels a little bit farther from the arrow head so that they look
+    more centred, do as follows:
+
+    >>> def default_formatter(astr):
+    ...   astr.label_displacement = "(0.45)"
+    >>> drawer.default_arrow_formatter = default_formatter
+    >>> print(drawer.draw(diagram, grid))
+    \xymatrix{
+    A \ar@{-->}[d]_(0.45){\exists !g\circ f} \ar[r]^(0.45){f} & B \ar[ld]^(0.45){g} \\
+    C &
+    }
+
+    In some diagrams some morphisms are drawn as curved arrows.
+    Consider the following diagram:
+
+    >>> D = Object("D")
+    >>> E = Object("E")
+    >>> h = NamedMorphism(D, A, "h")
+    >>> k = NamedMorphism(D, B, "k")
+    >>> diagram = Diagram([f, g, h, k])
+    >>> grid = DiagramGrid(diagram)
+    >>> drawer = XypicDiagramDrawer()
+    >>> print(drawer.draw(diagram, grid))
+    \xymatrix{
+    A \ar[r]_{f} & B \ar[d]^{g} & D \ar[l]^{k} \ar@/_3mm/[ll]_{h} \\
+    & C &
+    }
+
+    To control how far the morphisms are curved by default, one can
+    use the ``unit`` and ``default_curving_amount`` attributes:
+
+    >>> drawer.unit = "cm"
+    >>> drawer.default_curving_amount = 1
+    >>> print(drawer.draw(diagram, grid))
+    \xymatrix{
+    A \ar[r]_{f} & B \ar[d]^{g} & D \ar[l]^{k} \ar@/_1cm/[ll]_{h} \\
+    & C &
+    }
+
+    In some diagrams, there are multiple curved morphisms between the
+    same two objects.  To control by how much the curving changes
+    between two such successive morphisms, use
+    ``default_curving_step``:
+
+    >>> drawer.default_curving_step = 1
+    >>> h1 = NamedMorphism(A, D, "h1")
+    >>> diagram = Diagram([f, g, h, k, h1])
+    >>> grid = DiagramGrid(diagram)
+    >>> print(drawer.draw(diagram, grid))
+    \xymatrix{
+    A \ar[r]_{f} \ar@/^1cm/[rr]^{h_{1}} & B \ar[d]^{g} & D \ar[l]^{k} \ar@/_2cm/[ll]_{h} \\
+    & C &
+    }
+
+    The default value of ``default_curving_step`` is 4 units.
+
+    See Also
+    ========
+
+    draw, ArrowStringDescription
+    """
+    def __init__(self):
+        self.unit = "mm"
+        self.default_curving_amount = 3
+        self.default_curving_step = 4
+
+        # This dictionary maps properties to the corresponding arrow
+        # formatters.
+        self.arrow_formatters = {}
+
+        # This is the default arrow formatter which will be applied to
+        # each arrow independently of its properties.
+        self.default_arrow_formatter = None
+
+    @staticmethod
+    def _process_loop_morphism(i, j, grid, morphisms_str_info, object_coords):
+        """
+        Produces the information required for constructing the string
+        representation of a loop morphism.  This function is invoked
+        from ``_process_morphism``.
+
+        See Also
+        ========
+
+        _process_morphism
+        """
+        curving = ""
+        label_pos = "^"
+        looping_start = ""
+        looping_end = ""
+
+        # This is a loop morphism.  Count how many morphisms stick
+        # in each of the four quadrants.  Note that straight
+        # vertical and horizontal morphisms count in two quadrants
+        # at the same time (i.e., a morphism going up counts both
+        # in the first and the second quadrants).
+
+        # The usual numbering (counterclockwise) of quadrants
+        # applies.
+        quadrant = [0, 0, 0, 0]
+
+        obj = grid[i, j]
+
+        for m, m_str_info in morphisms_str_info.items():
+            if (m.domain == obj) and (m.codomain == obj):
+                # That's another loop morphism.  Check how it
+                # loops and mark the corresponding quadrants as
+                # busy.
+                (l_s, l_e) = (m_str_info.looping_start, m_str_info.looping_end)
+
+                if (l_s, l_e) == ("r", "u"):
+                    quadrant[0] += 1
+                elif (l_s, l_e) == ("u", "l"):
+                    quadrant[1] += 1
+                elif (l_s, l_e) == ("l", "d"):
+                    quadrant[2] += 1
+                elif (l_s, l_e) == ("d", "r"):
+                    quadrant[3] += 1
+
+                continue
+            if m.domain == obj:
+                (end_i, end_j) = object_coords[m.codomain]
+                goes_out = True
+            elif m.codomain == obj:
+                (end_i, end_j) = object_coords[m.domain]
+                goes_out = False
+            else:
+                continue
+
+            d_i = end_i - i
+            d_j = end_j - j
+            m_curving = m_str_info.curving
+
+            if (d_i != 0) and (d_j != 0):
+                # This is really a diagonal morphism.  Detect the
+                # quadrant.
+                if (d_i > 0) and (d_j > 0):
+                    quadrant[0] += 1
+                elif (d_i > 0) and (d_j < 0):
+                    quadrant[1] += 1
+                elif (d_i < 0) and (d_j < 0):
+                    quadrant[2] += 1
+                elif (d_i < 0) and (d_j > 0):
+                    quadrant[3] += 1
+            elif d_i == 0:
+                # Knowing where the other end of the morphism is
+                # and which way it goes, we now have to decide
+                # which quadrant is now the upper one and which is
+                # the lower one.
+                if d_j > 0:
+                    if goes_out:
+                        upper_quadrant = 0
+                        lower_quadrant = 3
+                    else:
+                        upper_quadrant = 3
+                        lower_quadrant = 0
+                else:
+                    if goes_out:
+                        upper_quadrant = 2
+                        lower_quadrant = 1
+                    else:
+                        upper_quadrant = 1
+                        lower_quadrant = 2
+
+                if m_curving:
+                    if m_curving == "^":
+                        quadrant[upper_quadrant] += 1
+                    elif m_curving == "_":
+                        quadrant[lower_quadrant] += 1
+                else:
+                    # This morphism counts in both upper and lower
+                    # quadrants.
+                    quadrant[upper_quadrant] += 1
+                    quadrant[lower_quadrant] += 1
+            elif d_j == 0:
+                # Knowing where the other end of the morphism is
+                # and which way it goes, we now have to decide
+                # which quadrant is now the left one and which is
+                # the right one.
+                if d_i < 0:
+                    if goes_out:
+                        left_quadrant = 1
+                        right_quadrant = 0
+                    else:
+                        left_quadrant = 0
+                        right_quadrant = 1
+                else:
+                    if goes_out:
+                        left_quadrant = 3
+                        right_quadrant = 2
+                    else:
+                        left_quadrant = 2
+                        right_quadrant = 3
+
+                if m_curving:
+                    if m_curving == "^":
+                        quadrant[left_quadrant] += 1
+                    elif m_curving == "_":
+                        quadrant[right_quadrant] += 1
+                else:
+                    # This morphism counts in both upper and lower
+                    # quadrants.
+                    quadrant[left_quadrant] += 1
+                    quadrant[right_quadrant] += 1
+
+        # Pick the freest quadrant to curve our morphism into.
+        freest_quadrant = 0
+        for i in range(4):
+            if quadrant[i] < quadrant[freest_quadrant]:
+                freest_quadrant = i
+
+        # Now set up proper looping.
+        (looping_start, looping_end) = [("r", "u"), ("u", "l"), ("l", "d"),
+                                        ("d", "r")][freest_quadrant]
+
+        return (curving, label_pos, looping_start, looping_end)
+
+    @staticmethod
+    def _process_horizontal_morphism(i, j, target_j, grid, morphisms_str_info,
+                                     object_coords):
+        """
+        Produces the information required for constructing the string
+        representation of a horizontal morphism.  This function is
+        invoked from ``_process_morphism``.
+
+        See Also
+        ========
+
+        _process_morphism
+        """
+        # The arrow is horizontal.  Check if it goes from left to
+        # right (``backwards == False``) or from right to left
+        # (``backwards == True``).
+        backwards = False
+        start = j
+        end = target_j
+        if end < start:
+            (start, end) = (end, start)
+            backwards = True
+
+        # Let's see which objects are there between ``start`` and
+        # ``end``, and then count how many morphisms stick out
+        # upwards, and how many stick out downwards.
+        #
+        # For example, consider the situation:
+        #
+        #    B1 C1
+        #    |  |
+        # A--B--C--D
+        #    |
+        #    B2
+        #
+        # Between the objects `A` and `D` there are two objects:
+        # `B` and `C`.  Further, there are two morphisms which
+        # stick out upward (the ones between `B1` and `B` and
+        # between `C` and `C1`) and one morphism which sticks out
+        # downward (the one between `B and `B2`).
+        #
+        # We need this information to decide how to curve the
+        # arrow between `A` and `D`.  First of all, since there
+        # are two objects between `A` and `D``, we must curve the
+        # arrow.  Then, we will have it curve downward, because
+        # there is more space (less morphisms stick out downward
+        # than upward).
+        up = []
+        down = []
+        straight_horizontal = []
+        for k in range(start + 1, end):
+            obj = grid[i, k]
+            if not obj:
+                continue
+
+            for m in morphisms_str_info:
+                if m.domain == obj:
+                    (end_i, end_j) = object_coords[m.codomain]
+                elif m.codomain == obj:
+                    (end_i, end_j) = object_coords[m.domain]
+                else:
+                    continue
+
+                if end_i > i:
+                    down.append(m)
+                elif end_i < i:
+                    up.append(m)
+                elif not morphisms_str_info[m].curving:
+                    # This is a straight horizontal morphism,
+                    # because it has no curving.
+                    straight_horizontal.append(m)
+
+        if len(up) < len(down):
+            # More morphisms stick out downward than upward, let's
+            # curve the morphism up.
+            if backwards:
+                curving = "_"
+                label_pos = "_"
+            else:
+                curving = "^"
+                label_pos = "^"
+
+            # Assure that the straight horizontal morphisms have
+            # their labels on the lower side of the arrow.
+            for m in straight_horizontal:
+                (i1, j1) = object_coords[m.domain]
+                (i2, j2) = object_coords[m.codomain]
+
+                m_str_info = morphisms_str_info[m]
+                if j1 < j2:
+                    m_str_info.label_position = "_"
+                else:
+                    m_str_info.label_position = "^"
+
+                # Don't allow any further modifications of the
+                # position of this label.
+                m_str_info.forced_label_position = True
+        else:
+            # More morphisms stick out downward than upward, let's
+            # curve the morphism up.
+            if backwards:
+                curving = "^"
+                label_pos = "^"
+            else:
+                curving = "_"
+                label_pos = "_"
+
+            # Assure that the straight horizontal morphisms have
+            # their labels on the upper side of the arrow.
+            for m in straight_horizontal:
+                (i1, j1) = object_coords[m.domain]
+                (i2, j2) = object_coords[m.codomain]
+
+                m_str_info = morphisms_str_info[m]
+                if j1 < j2:
+                    m_str_info.label_position = "^"
+                else:
+                    m_str_info.label_position = "_"
+
+                # Don't allow any further modifications of the
+                # position of this label.
+                m_str_info.forced_label_position = True
+
+        return (curving, label_pos)
+
+    @staticmethod
+    def _process_vertical_morphism(i, j, target_i, grid, morphisms_str_info,
+                                   object_coords):
+        """
+        Produces the information required for constructing the string
+        representation of a vertical morphism.  This function is
+        invoked from ``_process_morphism``.
+
+        See Also
+        ========
+
+        _process_morphism
+        """
+        # This arrow is vertical.  Check if it goes from top to
+        # bottom (``backwards == False``) or from bottom to top
+        # (``backwards == True``).
+        backwards = False
+        start = i
+        end = target_i
+        if end < start:
+            (start, end) = (end, start)
+            backwards = True
+
+        # Let's see which objects are there between ``start`` and
+        # ``end``, and then count how many morphisms stick out to
+        # the left, and how many stick out to the right.
+        #
+        # See the corresponding comment in the previous branch of
+        # this if-statement for more details.
+        left = []
+        right = []
+        straight_vertical = []
+        for k in range(start + 1, end):
+            obj = grid[k, j]
+            if not obj:
+                continue
+
+            for m in morphisms_str_info:
+                if m.domain == obj:
+                    (end_i, end_j) = object_coords[m.codomain]
+                elif m.codomain == obj:
+                    (end_i, end_j) = object_coords[m.domain]
+                else:
+                    continue
+
+                if end_j > j:
+                    right.append(m)
+                elif end_j < j:
+                    left.append(m)
+                elif not morphisms_str_info[m].curving:
+                    # This is a straight vertical morphism,
+                    # because it has no curving.
+                    straight_vertical.append(m)
+
+        if len(left) < len(right):
+            # More morphisms stick out to the left than to the
+            # right, let's curve the morphism to the right.
+            if backwards:
+                curving = "^"
+                label_pos = "^"
+            else:
+                curving = "_"
+                label_pos = "_"
+
+            # Assure that the straight vertical morphisms have
+            # their labels on the left side of the arrow.
+            for m in straight_vertical:
+                (i1, j1) = object_coords[m.domain]
+                (i2, j2) = object_coords[m.codomain]
+
+                m_str_info = morphisms_str_info[m]
+                if i1 < i2:
+                    m_str_info.label_position = "^"
+                else:
+                    m_str_info.label_position = "_"
+
+                # Don't allow any further modifications of the
+                # position of this label.
+                m_str_info.forced_label_position = True
+        else:
+            # More morphisms stick out to the right than to the
+            # left, let's curve the morphism to the left.
+            if backwards:
+                curving = "_"
+                label_pos = "_"
+            else:
+                curving = "^"
+                label_pos = "^"
+
+            # Assure that the straight vertical morphisms have
+            # their labels on the right side of the arrow.
+            for m in straight_vertical:
+                (i1, j1) = object_coords[m.domain]
+                (i2, j2) = object_coords[m.codomain]
+
+                m_str_info = morphisms_str_info[m]
+                if i1 < i2:
+                    m_str_info.label_position = "_"
+                else:
+                    m_str_info.label_position = "^"
+
+                # Don't allow any further modifications of the
+                # position of this label.
+                m_str_info.forced_label_position = True
+
+        return (curving, label_pos)
+
+    def _process_morphism(self, diagram, grid, morphism, object_coords,
+                          morphisms, morphisms_str_info):
+        """
+        Given the required information, produces the string
+        representation of ``morphism``.
+        """
+        def repeat_string_cond(times, str_gt, str_lt):
+            """
+            If ``times > 0``, repeats ``str_gt`` ``times`` times.
+            Otherwise, repeats ``str_lt`` ``-times`` times.
+            """
+            if times > 0:
+                return str_gt * times
+            else:
+                return str_lt * (-times)
+
+        def count_morphisms_undirected(A, B):
+            """
+            Counts how many processed morphisms there are between the
+            two supplied objects.
+            """
+            return len([m for m in morphisms_str_info
+                        if {m.domain, m.codomain} == {A, B}])
+
+        def count_morphisms_filtered(dom, cod, curving):
+            """
+            Counts the processed morphisms which go out of ``dom``
+            into ``cod`` with curving ``curving``.
+            """
+            return len([m for m, m_str_info in morphisms_str_info.items()
+                        if (m.domain, m.codomain) == (dom, cod) and
+                        (m_str_info.curving == curving)])
+
+        (i, j) = object_coords[morphism.domain]
+        (target_i, target_j) = object_coords[morphism.codomain]
+
+        # We now need to determine the direction of
+        # the arrow.
+        delta_i = target_i - i
+        delta_j = target_j - j
+        vertical_direction = repeat_string_cond(delta_i,
+                                                "d", "u")
+        horizontal_direction = repeat_string_cond(delta_j,
+                                                  "r", "l")
+
+        curving = ""
+        label_pos = "^"
+        looping_start = ""
+        looping_end = ""
+
+        if (delta_i == 0) and (delta_j == 0):
+            # This is a loop morphism.
+            (curving, label_pos, looping_start,
+             looping_end) = XypicDiagramDrawer._process_loop_morphism(
+                 i, j, grid, morphisms_str_info, object_coords)
+        elif (delta_i == 0) and (abs(j - target_j) > 1):
+            # This is a horizontal morphism.
+            (curving, label_pos) = XypicDiagramDrawer._process_horizontal_morphism(
+                i, j, target_j, grid, morphisms_str_info, object_coords)
+        elif (delta_j == 0) and (abs(i - target_i) > 1):
+            # This is a vertical morphism.
+            (curving, label_pos) = XypicDiagramDrawer._process_vertical_morphism(
+                i, j, target_i, grid, morphisms_str_info, object_coords)
+
+        count = count_morphisms_undirected(morphism.domain, morphism.codomain)
+        curving_amount = ""
+        if curving:
+            # This morphisms should be curved anyway.
+            curving_amount = self.default_curving_amount + count * \
+                self.default_curving_step
+        elif count:
+            # There are no objects between the domain and codomain of
+            # the current morphism, but this is not there already are
+            # some morphisms with the same domain and codomain, so we
+            # have to curve this one.
+            curving = "^"
+            filtered_morphisms = count_morphisms_filtered(
+                morphism.domain, morphism.codomain, curving)
+            curving_amount = self.default_curving_amount + \
+                filtered_morphisms * \
+                self.default_curving_step
+
+        # Let's now get the name of the morphism.
+        morphism_name = ""
+        if isinstance(morphism, IdentityMorphism):
+            morphism_name = "id_{%s}" + latex(grid[i, j])
+        elif isinstance(morphism, CompositeMorphism):
+            component_names = [latex(Symbol(component.name)) for
+                               component in morphism.components]
+            component_names.reverse()
+            morphism_name = "\\circ ".join(component_names)
+        elif isinstance(morphism, NamedMorphism):
+            morphism_name = latex(Symbol(morphism.name))
+
+        return ArrowStringDescription(
+            self.unit, curving, curving_amount, looping_start,
+            looping_end, horizontal_direction, vertical_direction,
+            label_pos, morphism_name)
+
+    @staticmethod
+    def _check_free_space_horizontal(dom_i, dom_j, cod_j, grid):
+        """
+        For a horizontal morphism, checks whether there is free space
+        (i.e., space not occupied by any objects) above the morphism
+        or below it.
+        """
+        if dom_j < cod_j:
+            (start, end) = (dom_j, cod_j)
+            backwards = False
+        else:
+            (start, end) = (cod_j, dom_j)
+            backwards = True
+
+        # Check for free space above.
+        if dom_i == 0:
+            free_up = True
+        else:
+            free_up = all(grid[dom_i - 1, j] for j in
+                          range(start, end + 1))
+
+        # Check for free space below.
+        if dom_i == grid.height - 1:
+            free_down = True
+        else:
+            free_down = not any(grid[dom_i + 1, j] for j in
+                                range(start, end + 1))
+
+        return (free_up, free_down, backwards)
+
+    @staticmethod
+    def _check_free_space_vertical(dom_i, cod_i, dom_j, grid):
+        """
+        For a vertical morphism, checks whether there is free space
+        (i.e., space not occupied by any objects) to the left of the
+        morphism or to the right of it.
+        """
+        if dom_i < cod_i:
+            (start, end) = (dom_i, cod_i)
+            backwards = False
+        else:
+            (start, end) = (cod_i, dom_i)
+            backwards = True
+
+        # Check if there's space to the left.
+        if dom_j == 0:
+            free_left = True
+        else:
+            free_left = not any(grid[i, dom_j - 1] for i in
+                                range(start, end + 1))
+
+        if dom_j == grid.width - 1:
+            free_right = True
+        else:
+            free_right = not any(grid[i, dom_j + 1] for i in
+                                 range(start, end + 1))
+
+        return (free_left, free_right, backwards)
+
+    @staticmethod
+    def _check_free_space_diagonal(dom_i, cod_i, dom_j, cod_j, grid):
+        """
+        For a diagonal morphism, checks whether there is free space
+        (i.e., space not occupied by any objects) above the morphism
+        or below it.
+        """
+        def abs_xrange(start, end):
+            if start < end:
+                return range(start, end + 1)
+            else:
+                return range(end, start + 1)
+
+        if dom_i < cod_i and dom_j < cod_j:
+            # This morphism goes from top-left to
+            # bottom-right.
+            (start_i, start_j) = (dom_i, dom_j)
+            (end_i, end_j) = (cod_i, cod_j)
+            backwards = False
+        elif dom_i > cod_i and dom_j > cod_j:
+            # This morphism goes from bottom-right to
+            # top-left.
+            (start_i, start_j) = (cod_i, cod_j)
+            (end_i, end_j) = (dom_i, dom_j)
+            backwards = True
+        if dom_i < cod_i and dom_j > cod_j:
+            # This morphism goes from top-right to
+            # bottom-left.
+            (start_i, start_j) = (dom_i, dom_j)
+            (end_i, end_j) = (cod_i, cod_j)
+            backwards = True
+        elif dom_i > cod_i and dom_j < cod_j:
+            # This morphism goes from bottom-left to
+            # top-right.
+            (start_i, start_j) = (cod_i, cod_j)
+            (end_i, end_j) = (dom_i, dom_j)
+            backwards = False
+
+        # This is an attempt at a fast and furious strategy to
+        # decide where there is free space on the two sides of
+        # a diagonal morphism.  For a diagonal morphism
+        # starting at ``(start_i, start_j)`` and ending at
+        # ``(end_i, end_j)`` the rectangle defined by these
+        # two points is considered.  The slope of the diagonal
+        # ``alpha`` is then computed.  Then, for every cell
+        # ``(i, j)`` within the rectangle, the slope
+        # ``alpha1`` of the line through ``(start_i,
+        # start_j)`` and ``(i, j)`` is considered.  If
+        # ``alpha1`` is between 0 and ``alpha``, the point
+        # ``(i, j)`` is above the diagonal, if ``alpha1`` is
+        # between ``alpha`` and infinity, the point is below
+        # the diagonal.  Also note that, with some beforehand
+        # precautions, this trick works for both the main and
+        # the secondary diagonals of the rectangle.
+
+        # I have considered the possibility to only follow the
+        # shorter diagonals immediately above and below the
+        # main (or secondary) diagonal.  This, however,
+        # wouldn't have resulted in much performance gain or
+        # better detection of outer edges, because of
+        # relatively small sizes of diagram grids, while the
+        # code would have become harder to understand.
+
+        alpha = float(end_i - start_i)/(end_j - start_j)
+        free_up = True
+        free_down = True
+        for i in abs_xrange(start_i, end_i):
+            if not free_up and not free_down:
+                break
+
+            for j in abs_xrange(start_j, end_j):
+                if not free_up and not free_down:
+                    break
+
+                if (i, j) == (start_i, start_j):
+                    continue
+
+                if j == start_j:
+                    alpha1 = "inf"
+                else:
+                    alpha1 = float(i - start_i)/(j - start_j)
+
+                if grid[i, j]:
+                    if (alpha1 == "inf") or (abs(alpha1) > abs(alpha)):
+                        free_down = False
+                    elif abs(alpha1) < abs(alpha):
+                        free_up = False
+
+        return (free_up, free_down, backwards)
+
+    def _push_labels_out(self, morphisms_str_info, grid, object_coords):
+        """
+        For all straight morphisms which form the visual boundary of
+        the laid out diagram, puts their labels on their outer sides.
+        """
+        def set_label_position(free1, free2, pos1, pos2, backwards, m_str_info):
+            """
+            Given the information about room available to one side and
+            to the other side of a morphism (``free1`` and ``free2``),
+            sets the position of the morphism label in such a way that
+            it is on the freer side.  This latter operations involves
+            choice between ``pos1`` and ``pos2``, taking ``backwards``
+            in consideration.
+
+            Thus this function will do nothing if either both ``free1
+            == True`` and ``free2 == True`` or both ``free1 == False``
+            and ``free2 == False``.  In either case, choosing one side
+            over the other presents no advantage.
+            """
+            if backwards:
+                (pos1, pos2) = (pos2, pos1)
+
+            if free1 and not free2:
+                m_str_info.label_position = pos1
+            elif free2 and not free1:
+                m_str_info.label_position = pos2
+
+        for m, m_str_info in morphisms_str_info.items():
+            if m_str_info.curving or m_str_info.forced_label_position:
+                # This is either a curved morphism, and curved
+                # morphisms have other magic, or the position of this
+                # label has already been fixed.
+                continue
+
+            if m.domain == m.codomain:
+                # This is a loop morphism, their labels, again have a
+                # different magic.
+                continue
+
+            (dom_i, dom_j) = object_coords[m.domain]
+            (cod_i, cod_j) = object_coords[m.codomain]
+
+            if dom_i == cod_i:
+                # Horizontal morphism.
+                (free_up, free_down,
+                 backwards) = XypicDiagramDrawer._check_free_space_horizontal(
+                     dom_i, dom_j, cod_j, grid)
+
+                set_label_position(free_up, free_down, "^", "_",
+                                   backwards, m_str_info)
+            elif dom_j == cod_j:
+                # Vertical morphism.
+                (free_left, free_right,
+                 backwards) = XypicDiagramDrawer._check_free_space_vertical(
+                     dom_i, cod_i, dom_j, grid)
+
+                set_label_position(free_left, free_right, "_", "^",
+                                   backwards, m_str_info)
+            else:
+                # A diagonal morphism.
+                (free_up, free_down,
+                 backwards) = XypicDiagramDrawer._check_free_space_diagonal(
+                     dom_i, cod_i, dom_j, cod_j, grid)
+
+                set_label_position(free_up, free_down, "^", "_",
+                                   backwards, m_str_info)
+
+    @staticmethod
+    def _morphism_sort_key(morphism, object_coords):
+        """
+        Provides a morphism sorting key such that horizontal or
+        vertical morphisms between neighbouring objects come
+        first, then horizontal or vertical morphisms between more
+        far away objects, and finally, all other morphisms.
+        """
+        (i, j) = object_coords[morphism.domain]
+        (target_i, target_j) = object_coords[morphism.codomain]
+
+        if morphism.domain == morphism.codomain:
+            # Loop morphisms should get after diagonal morphisms
+            # so that the proper direction in which to curve the
+            # loop can be determined.
+            return (3, 0, default_sort_key(morphism))
+
+        if target_i == i:
+            return (1, abs(target_j - j), default_sort_key(morphism))
+
+        if target_j == j:
+            return (1, abs(target_i - i), default_sort_key(morphism))
+
+        # Diagonal morphism.
+        return (2, 0, default_sort_key(morphism))
+
+    @staticmethod
+    def _build_xypic_string(diagram, grid, morphisms,
+                            morphisms_str_info, diagram_format):
+        """
+        Given a collection of :class:`ArrowStringDescription`
+        describing the morphisms of a diagram and the object layout
+        information of a diagram, produces the final Xy-pic picture.
+        """
+        # Build the mapping between objects and morphisms which have
+        # them as domains.
+        object_morphisms = {}
+        for obj in diagram.objects:
+            object_morphisms[obj] = []
+        for morphism in morphisms:
+            object_morphisms[morphism.domain].append(morphism)
+
+        result = "\\xymatrix%s{\n" % diagram_format
+
+        for i in range(grid.height):
+            for j in range(grid.width):
+                obj = grid[i, j]
+                if obj:
+                    result += latex(obj) + " "
+
+                    morphisms_to_draw = object_morphisms[obj]
+                    for morphism in morphisms_to_draw:
+                        result += str(morphisms_str_info[morphism]) + " "
+
+                # Don't put the & after the last column.
+                if j < grid.width - 1:
+                    result += "& "
+
+            # Don't put the line break after the last row.
+            if i < grid.height - 1:
+                result += "\\\\"
+            result += "\n"
+
+        result += "}\n"
+
+        return result
+
+    def draw(self, diagram, grid, masked=None, diagram_format=""):
+        r"""
+        Returns the Xy-pic representation of ``diagram`` laid out in
+        ``grid``.
+
+        Consider the following simple triangle diagram.
+
+        >>> from sympy.categories import Object, NamedMorphism, Diagram
+        >>> from sympy.categories import DiagramGrid, XypicDiagramDrawer
+        >>> A = Object("A")
+        >>> B = Object("B")
+        >>> C = Object("C")
+        >>> f = NamedMorphism(A, B, "f")
+        >>> g = NamedMorphism(B, C, "g")
+        >>> diagram = Diagram([f, g], {g * f: "unique"})
+
+        To draw this diagram, its objects need to be laid out with a
+        :class:`DiagramGrid`::
+
+        >>> grid = DiagramGrid(diagram)
+
+        Finally, the drawing:
+
+        >>> drawer = XypicDiagramDrawer()
+        >>> print(drawer.draw(diagram, grid))
+        \xymatrix{
+        A \ar[d]_{g\circ f} \ar[r]^{f} & B \ar[ld]^{g} \\
+        C &
+        }
+
+        The argument ``masked`` can be used to skip morphisms in the
+        presentation of the diagram:
+
+        >>> print(drawer.draw(diagram, grid, masked=[g * f]))
+        \xymatrix{
+        A \ar[r]^{f} & B \ar[ld]^{g} \\
+        C &
+        }
+
+        Finally, the ``diagram_format`` argument can be used to
+        specify the format string of the diagram.  For example, to
+        increase the spacing by 1 cm, proceeding as follows:
+
+        >>> print(drawer.draw(diagram, grid, diagram_format="@+1cm"))
+        \xymatrix@+1cm{
+        A \ar[d]_{g\circ f} \ar[r]^{f} & B \ar[ld]^{g} \\
+        C &
+        }
+
+        """
+        # This method works in several steps.  It starts by removing
+        # the masked morphisms, if necessary, and then maps objects to
+        # their positions in the grid (coordinate tuples).  Remember
+        # that objects are unique in ``Diagram`` and in the layout
+        # produced by ``DiagramGrid``, so every object is mapped to a
+        # single coordinate pair.
+        #
+        # The next step is the central step and is concerned with
+        # analysing the morphisms of the diagram and deciding how to
+        # draw them.  For example, how to curve the arrows is decided
+        # at this step.  The bulk of the analysis is implemented in
+        # ``_process_morphism``, to the result of which the
+        # appropriate formatters are applied.
+        #
+        # The result of the previous step is a list of
+        # ``ArrowStringDescription``.  After the analysis and
+        # application of formatters, some extra logic tries to assure
+        # better positioning of morphism labels (for example, an
+        # attempt is made to avoid the situations when arrows cross
+        # labels).  This functionality constitutes the next step and
+        # is implemented in ``_push_labels_out``.  Note that label
+        # positions which have been set via a formatter are not
+        # affected in this step.
+        #
+        # Finally, at the closing step, the array of
+        # ``ArrowStringDescription`` and the layout information
+        # incorporated in ``DiagramGrid`` are combined to produce the
+        # resulting Xy-pic picture.  This part of code lies in
+        # ``_build_xypic_string``.
+
+        if not masked:
+            morphisms_props = grid.morphisms
+        else:
+            morphisms_props = {}
+            for m, props in grid.morphisms.items():
+                if m in masked:
+                    continue
+                morphisms_props[m] = props
+
+        # Build the mapping between objects and their position in the
+        # grid.
+        object_coords = {}
+        for i in range(grid.height):
+            for j in range(grid.width):
+                if grid[i, j]:
+                    object_coords[grid[i, j]] = (i, j)
+
+        morphisms = sorted(morphisms_props,
+                           key=lambda m: XypicDiagramDrawer._morphism_sort_key(
+                               m, object_coords))
+
+        # Build the tuples defining the string representations of
+        # morphisms.
+        morphisms_str_info = {}
+        for morphism in morphisms:
+            string_description = self._process_morphism(
+                diagram, grid, morphism, object_coords, morphisms,
+                morphisms_str_info)
+
+            if self.default_arrow_formatter:
+                self.default_arrow_formatter(string_description)
+
+            for prop in morphisms_props[morphism]:
+                # prop is a Symbol.  TODO: Find out why.
+                if prop.name in self.arrow_formatters:
+                    formatter = self.arrow_formatters[prop.name]
+                    formatter(string_description)
+
+            morphisms_str_info[morphism] = string_description
+
+        # Reposition the labels a bit.
+        self._push_labels_out(morphisms_str_info, grid, object_coords)
+
+        return XypicDiagramDrawer._build_xypic_string(
+            diagram, grid, morphisms, morphisms_str_info, diagram_format)
+
+
+def xypic_draw_diagram(diagram, masked=None, diagram_format="",
+                       groups=None, **hints):
+    r"""
+    Provides a shortcut combining :class:`DiagramGrid` and
+    :class:`XypicDiagramDrawer`.  Returns an Xy-pic presentation of
+    ``diagram``.  The argument ``masked`` is a list of morphisms which
+    will be not be drawn.  The argument ``diagram_format`` is the
+    format string inserted after "\xymatrix".  ``groups`` should be a
+    set of logical groups.  The ``hints`` will be passed directly to
+    the constructor of :class:`DiagramGrid`.
+
+    For more information about the arguments, see the docstrings of
+    :class:`DiagramGrid` and ``XypicDiagramDrawer.draw``.
+
+    Examples
+    ========
+
+    >>> from sympy.categories import Object, NamedMorphism, Diagram
+    >>> from sympy.categories import xypic_draw_diagram
+    >>> A = Object("A")
+    >>> B = Object("B")
+    >>> C = Object("C")
+    >>> f = NamedMorphism(A, B, "f")
+    >>> g = NamedMorphism(B, C, "g")
+    >>> diagram = Diagram([f, g], {g * f: "unique"})
+    >>> print(xypic_draw_diagram(diagram))
+    \xymatrix{
+    A \ar[d]_{g\circ f} \ar[r]^{f} & B \ar[ld]^{g} \\
+    C &
+    }
+
+    See Also
+    ========
+
+    XypicDiagramDrawer, DiagramGrid
+    """
+    grid = DiagramGrid(diagram, groups, **hints)
+    drawer = XypicDiagramDrawer()
+    return drawer.draw(diagram, grid, masked, diagram_format)
+
+
+@doctest_depends_on(exe=('latex', 'dvipng'), modules=('pyglet',))
+def preview_diagram(diagram, masked=None, diagram_format="", groups=None,
+                    output='png', viewer=None, euler=True, **hints):
+    """
+    Combines the functionality of ``xypic_draw_diagram`` and
+    ``sympy.printing.preview``.  The arguments ``masked``,
+    ``diagram_format``, ``groups``, and ``hints`` are passed to
+    ``xypic_draw_diagram``, while ``output``, ``viewer, and ``euler``
+    are passed to ``preview``.
+
+    Examples
+    ========
+
+    >>> from sympy.categories import Object, NamedMorphism, Diagram
+    >>> from sympy.categories import preview_diagram
+    >>> A = Object("A")
+    >>> B = Object("B")
+    >>> C = Object("C")
+    >>> f = NamedMorphism(A, B, "f")
+    >>> g = NamedMorphism(B, C, "g")
+    >>> d = Diagram([f, g], {g * f: "unique"})
+    >>> preview_diagram(d)
+
+    See Also
+    ========
+
+    XypicDiagramDrawer
+    """
+    from sympy.printing import preview
+    latex_output = xypic_draw_diagram(diagram, masked, diagram_format,
+                                      groups, **hints)
+    preview(latex_output, output, viewer, euler, ("xypic",))

.venv/lib/python3.13/site-packages/sympy/categories/tests/test_baseclasses.py

@@ -0,0 +1,209 @@
+from sympy.categories import (Object, Morphism, IdentityMorphism,
+                              NamedMorphism, CompositeMorphism,
+                              Diagram, Category)
+from sympy.categories.baseclasses import Class
+from sympy.testing.pytest import raises
+from sympy.core.containers import (Dict, Tuple)
+from sympy.sets import EmptySet
+from sympy.sets.sets import FiniteSet
+
+
+def test_morphisms():
+    A = Object("A")
+    B = Object("B")
+    C = Object("C")
+    D = Object("D")
+
+    # Test the base morphism.
+    f = NamedMorphism(A, B, "f")
+    assert f.domain == A
+    assert f.codomain == B
+    assert f == NamedMorphism(A, B, "f")
+
+    # Test identities.
+    id_A = IdentityMorphism(A)
+    id_B = IdentityMorphism(B)
+    assert id_A.domain == A
+    assert id_A.codomain == A
+    assert id_A == IdentityMorphism(A)
+    assert id_A != id_B
+
+    # Test named morphisms.
+    g = NamedMorphism(B, C, "g")
+    assert g.name == "g"
+    assert g != f
+    assert g == NamedMorphism(B, C, "g")
+    assert g != NamedMorphism(B, C, "f")
+
+    # Test composite morphisms.
+    assert f == CompositeMorphism(f)
+
+    k = g.compose(f)
+    assert k.domain == A
+    assert k.codomain == C
+    assert k.components == Tuple(f, g)
+    assert g * f == k
+    assert CompositeMorphism(f, g) == k
+
+    assert CompositeMorphism(g * f) == g * f
+
+    # Test the associativity of composition.
+    h = NamedMorphism(C, D, "h")
+
+    p = h * g
+    u = h * g * f
+
+    assert h * k == u
+    assert p * f == u
+    assert CompositeMorphism(f, g, h) == u
+
+    # Test flattening.
+    u2 = u.flatten("u")
+    assert isinstance(u2, NamedMorphism)
+    assert u2.name == "u"
+    assert u2.domain == A
+    assert u2.codomain == D
+
+    # Test identities.
+    assert f * id_A == f
+    assert id_B * f == f
+    assert id_A * id_A == id_A
+    assert CompositeMorphism(id_A) == id_A
+
+    # Test bad compositions.
+    raises(ValueError, lambda: f * g)
+
+    raises(TypeError, lambda: f.compose(None))
+    raises(TypeError, lambda: id_A.compose(None))
+    raises(TypeError, lambda: f * None)
+    raises(TypeError, lambda: id_A * None)
+
+    raises(TypeError, lambda: CompositeMorphism(f, None, 1))
+
+    raises(ValueError, lambda: NamedMorphism(A, B, ""))
+    raises(NotImplementedError, lambda: Morphism(A, B))
+
+
+def test_diagram():
+    A = Object("A")
+    B = Object("B")
+    C = Object("C")
+
+    f = NamedMorphism(A, B, "f")
+    g = NamedMorphism(B, C, "g")
+    id_A = IdentityMorphism(A)
+    id_B = IdentityMorphism(B)
+
+    empty = EmptySet
+
+    # Test the addition of identities.
+    d1 = Diagram([f])
+
+    assert d1.objects == FiniteSet(A, B)
+    assert d1.hom(A, B) == (FiniteSet(f), empty)
+    assert d1.hom(A, A) == (FiniteSet(id_A), empty)
+    assert d1.hom(B, B) == (FiniteSet(id_B), empty)
+
+    assert d1 == Diagram([id_A, f])
+    assert d1 == Diagram([f, f])
+
+    # Test the addition of composites.
+    d2 = Diagram([f, g])
+    homAC = d2.hom(A, C)[0]
+
+    assert d2.objects == FiniteSet(A, B, C)
+    assert g * f in d2.premises.keys()
+    assert homAC == FiniteSet(g * f)
+
+    # Test equality, inequality and hash.
+    d11 = Diagram([f])
+
+    assert d1 == d11
+    assert d1 != d2
+    assert hash(d1) == hash(d11)
+
+    d11 = Diagram({f: "unique"})
+    assert d1 != d11
+
+    # Make sure that (re-)adding composites (with new properties)
+    # works as expected.
+    d = Diagram([f, g], {g * f: "unique"})
+    assert d.conclusions == Dict({g * f: FiniteSet("unique")})
+
+    # Check the hom-sets when there are premises and conclusions.
+    assert d.hom(A, C) == (FiniteSet(g * f), FiniteSet(g * f))
+    d = Diagram([f, g], [g * f])
+    assert d.hom(A, C) == (FiniteSet(g * f), FiniteSet(g * f))
+
+    # Check how the properties of composite morphisms are computed.
+    d = Diagram({f: ["unique", "isomorphism"], g: "unique"})
+    assert d.premises[g * f] == FiniteSet("unique")
+
+    # Check that conclusion morphisms with new objects are not allowed.
+    d = Diagram([f], [g])
+    assert d.conclusions == Dict({})
+
+    # Test an empty diagram.
+    d = Diagram()
+    assert d.premises == Dict({})
+    assert d.conclusions == Dict({})
+    assert d.objects == empty
+
+    # Check a SymPy Dict object.
+    d = Diagram(Dict({f: FiniteSet("unique", "isomorphism"), g: "unique"}))
+    assert d.premises[g * f] == FiniteSet("unique")
+
+    # Check the addition of components of composite morphisms.
+    d = Diagram([g * f])
+    assert f in d.premises
+    assert g in d.premises
+
+    # Check subdiagrams.
+    d = Diagram([f, g], {g * f: "unique"})
+
+    d1 = Diagram([f])
+    assert d.is_subdiagram(d1)
+    assert not d1.is_subdiagram(d)
+
+    d = Diagram([NamedMorphism(B, A, "f'")])
+    assert not d.is_subdiagram(d1)
+    assert not d1.is_subdiagram(d)
+
+    d1 = Diagram([f, g], {g * f: ["unique", "something"]})
+    assert not d.is_subdiagram(d1)
+    assert not d1.is_subdiagram(d)
+
+    d = Diagram({f: "blooh"})
+    d1 = Diagram({f: "bleeh"})
+    assert not d.is_subdiagram(d1)
+    assert not d1.is_subdiagram(d)
+
+    d = Diagram([f, g], {f: "unique", g * f: "veryunique"})
+    d1 = d.subdiagram_from_objects(FiniteSet(A, B))
+    assert d1 == Diagram([f], {f: "unique"})
+    raises(ValueError, lambda: d.subdiagram_from_objects(FiniteSet(A,
+           Object("D"))))
+
+    raises(ValueError, lambda: Diagram({IdentityMorphism(A): "unique"}))
+
+
+def test_category():
+    A = Object("A")
+    B = Object("B")
+    C = Object("C")
+
+    f = NamedMorphism(A, B, "f")
+    g = NamedMorphism(B, C, "g")
+
+    d1 = Diagram([f, g])
+    d2 = Diagram([f])
+
+    objects = d1.objects | d2.objects
+
+    K = Category("K", objects, commutative_diagrams=[d1, d2])
+
+    assert K.name == "K"
+    assert K.objects == Class(objects)
+    assert K.commutative_diagrams == FiniteSet(d1, d2)
+
+    raises(ValueError, lambda: Category(""))

.venv/lib/python3.13/site-packages/sympy/categories/tests/test_drawing.py

@@ -0,0 +1,919 @@
+from sympy.categories.diagram_drawing import _GrowableGrid, ArrowStringDescription
+from sympy.categories import (DiagramGrid, Object, NamedMorphism,
+                              Diagram, XypicDiagramDrawer, xypic_draw_diagram)
+from sympy.sets.sets import FiniteSet
+
+
+def test_GrowableGrid():
+    grid = _GrowableGrid(1, 2)
+
+    # Check dimensions.
+    assert grid.width == 1
+    assert grid.height == 2
+
+    # Check initialization of elements.
+    assert grid[0, 0] is None
+    assert grid[1, 0] is None
+
+    # Check assignment to elements.
+    grid[0, 0] = 1
+    grid[1, 0] = "two"
+
+    assert grid[0, 0] == 1
+    assert grid[1, 0] == "two"
+
+    # Check appending a row.
+    grid.append_row()
+
+    assert grid.width == 1
+    assert grid.height == 3
+
+    assert grid[0, 0] == 1
+    assert grid[1, 0] == "two"
+    assert grid[2, 0] is None
+
+    # Check appending a column.
+    grid.append_column()
+    assert grid.width == 2
+    assert grid.height == 3
+
+    assert grid[0, 0] == 1
+    assert grid[1, 0] == "two"
+    assert grid[2, 0] is None
+
+    assert grid[0, 1] is None
+    assert grid[1, 1] is None
+    assert grid[2, 1] is None
+
+    grid = _GrowableGrid(1, 2)
+    grid[0, 0] = 1
+    grid[1, 0] = "two"
+
+    # Check prepending a row.
+    grid.prepend_row()
+    assert grid.width == 1
+    assert grid.height == 3
+
+    assert grid[0, 0] is None
+    assert grid[1, 0] == 1
+    assert grid[2, 0] == "two"
+
+    # Check prepending a column.
+    grid.prepend_column()
+    assert grid.width == 2
+    assert grid.height == 3
+
+    assert grid[0, 0] is None
+    assert grid[1, 0] is None
+    assert grid[2, 0] is None
+
+    assert grid[0, 1] is None
+    assert grid[1, 1] == 1
+    assert grid[2, 1] == "two"
+
+
+def test_DiagramGrid():
+    # Set up some objects and morphisms.
+    A = Object("A")
+    B = Object("B")
+    C = Object("C")
+    D = Object("D")
+    E = Object("E")
+
+    f = NamedMorphism(A, B, "f")
+    g = NamedMorphism(B, C, "g")
+    h = NamedMorphism(D, A, "h")
+    k = NamedMorphism(D, B, "k")
+
+    # A one-morphism diagram.
+    d = Diagram([f])
+    grid = DiagramGrid(d)
+
+    assert grid.width == 2
+    assert grid.height == 1
+    assert grid[0, 0] == A
+    assert grid[0, 1] == B
+    assert grid.morphisms == {f: FiniteSet()}
+
+    # A triangle.
+    d = Diagram([f, g], {g * f: "unique"})
+    grid = DiagramGrid(d)
+
+    assert grid.width == 2
+    assert grid.height == 2
+    assert grid[0, 0] == A
+    assert grid[0, 1] == B
+    assert grid[1, 0] == C
+    assert grid[1, 1] is None
+    assert grid.morphisms == {f: FiniteSet(), g: FiniteSet(),
+                              g * f: FiniteSet("unique")}
+
+    # A triangle with a "loop" morphism.
+    l_A = NamedMorphism(A, A, "l_A")
+    d = Diagram([f, g, l_A])
+    grid = DiagramGrid(d)
+
+    assert grid.width == 2
+    assert grid.height == 2
+    assert grid[0, 0] == A
+    assert grid[0, 1] == B
+    assert grid[1, 0] is None
+    assert grid[1, 1] == C
+    assert grid.morphisms == {f: FiniteSet(), g: FiniteSet(), l_A: FiniteSet()}
+
+    # A simple diagram.
+    d = Diagram([f, g, h, k])
+    grid = DiagramGrid(d)
+
+    assert grid.width == 3
+    assert grid.height == 2
+    assert grid[0, 0] == A
+    assert grid[0, 1] == B
+    assert grid[0, 2] == D
+    assert grid[1, 0] is None
+    assert grid[1, 1] == C
+    assert grid[1, 2] is None
+    assert grid.morphisms == {f: FiniteSet(), g: FiniteSet(), h: FiniteSet(),
+                              k: FiniteSet()}
+
+    assert str(grid) == '[[Object("A"), Object("B"), Object("D")], ' \
+        '[None, Object("C"), None]]'
+
+    # A chain of morphisms.
+    f = NamedMorphism(A, B, "f")
+    g = NamedMorphism(B, C, "g")
+    h = NamedMorphism(C, D, "h")
+    k = NamedMorphism(D, E, "k")
+    d = Diagram([f, g, h, k])
+    grid = DiagramGrid(d)
+
+    assert grid.width == 3
+    assert grid.height == 3
+    assert grid[0, 0] == A
+    assert grid[0, 1] == B
+    assert grid[0, 2] is None
+    assert grid[1, 0] is None
+    assert grid[1, 1] == C
+    assert grid[1, 2] == D
+    assert grid[2, 0] is None
+    assert grid[2, 1] is None
+    assert grid[2, 2] == E
+    assert grid.morphisms == {f: FiniteSet(), g: FiniteSet(), h: FiniteSet(),
+                              k: FiniteSet()}
+
+    # A square.
+    f = NamedMorphism(A, B, "f")
+    g = NamedMorphism(B, D, "g")
+    h = NamedMorphism(A, C, "h")
+    k = NamedMorphism(C, D, "k")
+    d = Diagram([f, g, h, k])
+    grid = DiagramGrid(d)
+
+    assert grid.width == 2
+    assert grid.height == 2
+    assert grid[0, 0] == A
+    assert grid[0, 1] == B
+    assert grid[1, 0] == C
+    assert grid[1, 1] == D
+    assert grid.morphisms == {f: FiniteSet(), g: FiniteSet(), h: FiniteSet(),
+                              k: FiniteSet()}
+
+    # A strange diagram which resulted from a typo when creating a
+    # test for five lemma, but which allowed to stop one extra problem
+    # in the algorithm.
+    A = Object("A")
+    B = Object("B")
+    C = Object("C")
+    D = Object("D")
+    E = Object("E")
+    A_ = Object("A'")
+    B_ = Object("B'")
+    C_ = Object("C'")
+    D_ = Object("D'")
+    E_ = Object("E'")
+
+    f = NamedMorphism(A, B, "f")
+    g = NamedMorphism(B, C, "g")
+    h = NamedMorphism(C, D, "h")
+    i = NamedMorphism(D, E, "i")
+
+    # These 4 morphisms should be between primed objects.
+    j = NamedMorphism(A, B, "j")
+    k = NamedMorphism(B, C, "k")
+    l = NamedMorphism(C, D, "l")
+    m = NamedMorphism(D, E, "m")
+
+    o = NamedMorphism(A, A_, "o")
+    p = NamedMorphism(B, B_, "p")
+    q = NamedMorphism(C, C_, "q")
+    r = NamedMorphism(D, D_, "r")
+    s = NamedMorphism(E, E_, "s")
+
+    d = Diagram([f, g, h, i, j, k, l, m, o, p, q, r, s])
+    grid = DiagramGrid(d)
+
+    assert grid.width == 3
+    assert grid.height == 4
+    assert grid[0, 0] is None
+    assert grid[0, 1] == A
+    assert grid[0, 2] == A_
+    assert grid[1, 0] == C
+    assert grid[1, 1] == B
+    assert grid[1, 2] == B_
+    assert grid[2, 0] == C_
+    assert grid[2, 1] == D
+    assert grid[2, 2] == D_
+    assert grid[3, 0] is None
+    assert grid[3, 1] == E
+    assert grid[3, 2] == E_
+
+    morphisms = {}
+    for m in [f, g, h, i, j, k, l, m, o, p, q, r, s]:
+        morphisms[m] = FiniteSet()
+    assert grid.morphisms == morphisms
+
+    # A cube.
+    A1 = Object("A1")
+    A2 = Object("A2")
+    A3 = Object("A3")
+    A4 = Object("A4")
+    A5 = Object("A5")
+    A6 = Object("A6")
+    A7 = Object("A7")
+    A8 = Object("A8")
+
+    # The top face of the cube.
+    f1 = NamedMorphism(A1, A2, "f1")
+    f2 = NamedMorphism(A1, A3, "f2")
+    f3 = NamedMorphism(A2, A4, "f3")
+    f4 = NamedMorphism(A3, A4, "f3")
+
+    # The bottom face of the cube.
+    f5 = NamedMorphism(A5, A6, "f5")
+    f6 = NamedMorphism(A5, A7, "f6")
+    f7 = NamedMorphism(A6, A8, "f7")
+    f8 = NamedMorphism(A7, A8, "f8")
+
+    # The remaining morphisms.
+    f9 = NamedMorphism(A1, A5, "f9")
+    f10 = NamedMorphism(A2, A6, "f10")
+    f11 = NamedMorphism(A3, A7, "f11")
+    f12 = NamedMorphism(A4, A8, "f11")
+
+    d = Diagram([f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11, f12])
+    grid = DiagramGrid(d)
+
+    assert grid.width == 4
+    assert grid.height == 3
+    assert grid[0, 0] is None
+    assert grid[0, 1] == A5
+    assert grid[0, 2] == A6
+    assert grid[0, 3] is None
+    assert grid[1, 0] is None
+    assert grid[1, 1] == A1
+    assert grid[1, 2] == A2
+    assert grid[1, 3] is None
+    assert grid[2, 0] == A7
+    assert grid[2, 1] == A3
+    assert grid[2, 2] == A4
+    assert grid[2, 3] == A8
+
+    morphisms = {}
+    for m in [f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11, f12]:
+        morphisms[m] = FiniteSet()
+    assert grid.morphisms == morphisms
+
+    # A line diagram.
+    A = Object("A")
+    B = Object("B")
+    C = Object("C")
+    D = Object("D")
+    E = Object("E")
+
+    f = NamedMorphism(A, B, "f")
+    g = NamedMorphism(B, C, "g")
+    h = NamedMorphism(C, D, "h")
+    i = NamedMorphism(D, E, "i")
+    d = Diagram([f, g, h, i])
+    grid = DiagramGrid(d, layout="sequential")
+
+    assert grid.width == 5
+    assert grid.height == 1
+    assert grid[0, 0] == A
+    assert grid[0, 1] == B
+    assert grid[0, 2] == C
+    assert grid[0, 3] == D
+    assert grid[0, 4] == E
+    assert grid.morphisms == {f: FiniteSet(), g: FiniteSet(), h: FiniteSet(),
+                              i: FiniteSet()}
+
+    # Test the transposed version.
+    grid = DiagramGrid(d, layout="sequential", transpose=True)
+
+    assert grid.width == 1
+    assert grid.height == 5
+    assert grid[0, 0] == A
+    assert grid[1, 0] == B
+    assert grid[2, 0] == C
+    assert grid[3, 0] == D
+    assert grid[4, 0] == E
+    assert grid.morphisms == {f: FiniteSet(), g: FiniteSet(), h: FiniteSet(),
+                              i: FiniteSet()}
+
+    # A pullback.
+    m1 = NamedMorphism(A, B, "m1")
+    m2 = NamedMorphism(A, C, "m2")
+    s1 = NamedMorphism(B, D, "s1")
+    s2 = NamedMorphism(C, D, "s2")
+    f1 = NamedMorphism(E, B, "f1")
+    f2 = NamedMorphism(E, C, "f2")
+    g = NamedMorphism(E, A, "g")
+
+    d = Diagram([m1, m2, s1, s2, f1, f2], {g: "unique"})
+    grid = DiagramGrid(d)
+
+    assert grid.width == 3
+    assert grid.height == 2
+    assert grid[0, 0] == A
+    assert grid[0, 1] == B
+    assert grid[0, 2] == E
+    assert grid[1, 0] == C
+    assert grid[1, 1] == D
+    assert grid[1, 2] is None
+
+    morphisms = {g: FiniteSet("unique")}
+    for m in [m1, m2, s1, s2, f1, f2]:
+        morphisms[m] = FiniteSet()
+    assert grid.morphisms == morphisms
+
+    # Test the pullback with sequential layout, just for stress
+    # testing.
+    grid = DiagramGrid(d, layout="sequential")
+
+    assert grid.width == 5
+    assert grid.height == 1
+    assert grid[0, 0] == D
+    assert grid[0, 1] == B
+    assert grid[0, 2] == A
+    assert grid[0, 3] == C
+    assert grid[0, 4] == E
+    assert grid.morphisms == morphisms
+
+    # Test a pullback with object grouping.
+    grid = DiagramGrid(d, groups=FiniteSet(E, FiniteSet(A, B, C, D)))
+
+    assert grid.width == 3
+    assert grid.height == 2
+    assert grid[0, 0] == E
+    assert grid[0, 1] == A
+    assert grid[0, 2] == B
+    assert grid[1, 0] is None
+    assert grid[1, 1] == C
+    assert grid[1, 2] == D
+    assert grid.morphisms == morphisms
+
+    # Five lemma, actually.
+    A = Object("A")
+    B = Object("B")
+    C = Object("C")
+    D = Object("D")
+    E = Object("E")
+    A_ = Object("A'")
+    B_ = Object("B'")
+    C_ = Object("C'")
+    D_ = Object("D'")
+    E_ = Object("E'")
+
+    f = NamedMorphism(A, B, "f")
+    g = NamedMorphism(B, C, "g")
+    h = NamedMorphism(C, D, "h")
+    i = NamedMorphism(D, E, "i")
+
+    j = NamedMorphism(A_, B_, "j")
+    k = NamedMorphism(B_, C_, "k")
+    l = NamedMorphism(C_, D_, "l")
+    m = NamedMorphism(D_, E_, "m")
+
+    o = NamedMorphism(A, A_, "o")
+    p = NamedMorphism(B, B_, "p")
+    q = NamedMorphism(C, C_, "q")
+    r = NamedMorphism(D, D_, "r")
+    s = NamedMorphism(E, E_, "s")
+
+    d = Diagram([f, g, h, i, j, k, l, m, o, p, q, r, s])
+    grid = DiagramGrid(d)
+
+    assert grid.width == 5
+    assert grid.height == 3
+    assert grid[0, 0] is None
+    assert grid[0, 1] == A
+    assert grid[0, 2] == A_
+    assert grid[0, 3] is None
+    assert grid[0, 4] is None
+    assert grid[1, 0] == C
+    assert grid[1, 1] == B
+    assert grid[1, 2] == B_
+    assert grid[1, 3] == C_
+    assert grid[1, 4] is None
+    assert grid[2, 0] == D
+    assert grid[2, 1] == E
+    assert grid[2, 2] is None
+    assert grid[2, 3] == D_
+    assert grid[2, 4] == E_
+
+    morphisms = {}
+    for m in [f, g, h, i, j, k, l, m, o, p, q, r, s]:
+        morphisms[m] = FiniteSet()
+    assert grid.morphisms == morphisms
+
+    # Test the five lemma with object grouping.
+    grid = DiagramGrid(d, FiniteSet(
+        FiniteSet(A, B, C, D, E), FiniteSet(A_, B_, C_, D_, E_)))
+
+    assert grid.width == 6
+    assert grid.height == 3
+    assert grid[0, 0] == A
+    assert grid[0, 1] == B
+    assert grid[0, 2] is None
+    assert grid[0, 3] == A_
+    assert grid[0, 4] == B_
+    assert grid[0, 5] is None
+    assert grid[1, 0] is None
+    assert grid[1, 1] == C
+    assert grid[1, 2] == D
+    assert grid[1, 3] is None
+    assert grid[1, 4] == C_
+    assert grid[1, 5] == D_
+    assert grid[2, 0] is None
+    assert grid[2, 1] is None
+    assert grid[2, 2] == E
+    assert grid[2, 3] is None
+    assert grid[2, 4] is None
+    assert grid[2, 5] == E_
+    assert grid.morphisms == morphisms
+
+    # Test the five lemma with object grouping, but mixing containers
+    # to represent groups.
+    grid = DiagramGrid(d, [(A, B, C, D, E), {A_, B_, C_, D_, E_}])
+
+    assert grid.width == 6
+    assert grid.height == 3
+    assert grid[0, 0] == A
+    assert grid[0, 1] == B
+    assert grid[0, 2] is None
+    assert grid[0, 3] == A_
+    assert grid[0, 4] == B_
+    assert grid[0, 5] is None
+    assert grid[1, 0] is None
+    assert grid[1, 1] == C
+    assert grid[1, 2] == D
+    assert grid[1, 3] is None
+    assert grid[1, 4] == C_
+    assert grid[1, 5] == D_
+    assert grid[2, 0] is None
+    assert grid[2, 1] is None
+    assert grid[2, 2] == E
+    assert grid[2, 3] is None
+    assert grid[2, 4] is None
+    assert grid[2, 5] == E_
+    assert grid.morphisms == morphisms
+
+    # Test the five lemma with object grouping and hints.
+    grid = DiagramGrid(d, {
+        FiniteSet(A, B, C, D, E): {"layout": "sequential",
+                                   "transpose": True},
+        FiniteSet(A_, B_, C_, D_, E_): {"layout": "sequential",
+                                        "transpose": True}},
+        transpose=True)
+
+    assert grid.width == 5
+    assert grid.height == 2
+    assert grid[0, 0] == A
+    assert grid[0, 1] == B
+    assert grid[0, 2] == C
+    assert grid[0, 3] == D
+    assert grid[0, 4] == E
+    assert grid[1, 0] == A_
+    assert grid[1, 1] == B_
+    assert grid[1, 2] == C_
+    assert grid[1, 3] == D_
+    assert grid[1, 4] == E_
+    assert grid.morphisms == morphisms
+
+    # A two-triangle disconnected diagram.
+    f = NamedMorphism(A, B, "f")
+    g = NamedMorphism(B, C, "g")
+    f_ = NamedMorphism(A_, B_, "f")
+    g_ = NamedMorphism(B_, C_, "g")
+    d = Diagram([f, g, f_, g_], {g * f: "unique", g_ * f_: "unique"})
+    grid = DiagramGrid(d)
+
+    assert grid.width == 4
+    assert grid.height == 2
+    assert grid[0, 0] == A
+    assert grid[0, 1] == B
+    assert grid[0, 2] == A_
+    assert grid[0, 3] == B_
+    assert grid[1, 0] == C
+    assert grid[1, 1] is None
+    assert grid[1, 2] == C_
+    assert grid[1, 3] is None
+    assert grid.morphisms == {f: FiniteSet(), g: FiniteSet(), f_: FiniteSet(),
+                              g_: FiniteSet(), g * f: FiniteSet("unique"),
+                              g_ * f_: FiniteSet("unique")}
+
+    # A two-morphism disconnected diagram.
+    f = NamedMorphism(A, B, "f")
+    g = NamedMorphism(C, D, "g")
+    d = Diagram([f, g])
+    grid = DiagramGrid(d)
+
+    assert grid.width == 4
+    assert grid.height == 1
+    assert grid[0, 0] == A
+    assert grid[0, 1] == B
+    assert grid[0, 2] == C
+    assert grid[0, 3] == D
+    assert grid.morphisms == {f: FiniteSet(), g: FiniteSet()}
+
+    # Test a one-object diagram.
+    f = NamedMorphism(A, A, "f")
+    d = Diagram([f])
+    grid = DiagramGrid(d)
+
+    assert grid.width == 1
+    assert grid.height == 1
+    assert grid[0, 0] == A
+
+    # Test a two-object disconnected diagram.
+    g = NamedMorphism(B, B, "g")
+    d = Diagram([f, g])
+    grid = DiagramGrid(d)
+
+    assert grid.width == 2
+    assert grid.height == 1
+    assert grid[0, 0] == A
+    assert grid[0, 1] == B
+
+
+def test_DiagramGrid_pseudopod():
+    # Test a diagram in which even growing a pseudopod does not
+    # eventually help.
+    A = Object("A")
+    B = Object("B")
+    C = Object("C")
+    D = Object("D")
+    E = Object("E")
+    F = Object("F")
+    A_ = Object("A'")
+    B_ = Object("B'")
+    C_ = Object("C'")
+    D_ = Object("D'")
+    E_ = Object("E'")
+
+    f1 = NamedMorphism(A, B, "f1")
+    f2 = NamedMorphism(A, C, "f2")
+    f3 = NamedMorphism(A, D, "f3")
+    f4 = NamedMorphism(A, E, "f4")
+    f5 = NamedMorphism(A, A_, "f5")
+    f6 = NamedMorphism(A, B_, "f6")
+    f7 = NamedMorphism(A, C_, "f7")
+    f8 = NamedMorphism(A, D_, "f8")
+    f9 = NamedMorphism(A, E_, "f9")
+    f10 = NamedMorphism(A, F, "f10")
+    d = Diagram([f1, f2, f3, f4, f5, f6, f7, f8, f9, f10])
+    grid = DiagramGrid(d)
+
+    assert grid.width == 5
+    assert grid.height == 3
+    assert grid[0, 0] == E
+    assert grid[0, 1] == C
+    assert grid[0, 2] == C_
+    assert grid[0, 3] == E_
+    assert grid[0, 4] == F
+    assert grid[1, 0] == D
+    assert grid[1, 1] == A
+    assert grid[1, 2] == A_
+    assert grid[1, 3] is None
+    assert grid[1, 4] is None
+    assert grid[2, 0] == D_
+    assert grid[2, 1] == B
+    assert grid[2, 2] == B_
+    assert grid[2, 3] is None
+    assert grid[2, 4] is None
+
+    morphisms = {}
+    for f in [f1, f2, f3, f4, f5, f6, f7, f8, f9, f10]:
+        morphisms[f] = FiniteSet()
+    assert grid.morphisms == morphisms
+
+
+def test_ArrowStringDescription():
+    astr = ArrowStringDescription("cm", "", None, "", "", "d", "r", "_", "f")
+    assert str(astr) == "\\ar[dr]_{f}"
+
+    astr = ArrowStringDescription("cm", "", 12, "", "", "d", "r", "_", "f")
+    assert str(astr) == "\\ar[dr]_{f}"
+
+    astr = ArrowStringDescription("cm", "^", 12, "", "", "d", "r", "_", "f")
+    assert str(astr) == "\\ar@/^12cm/[dr]_{f}"
+
+    astr = ArrowStringDescription("cm", "", 12, "r", "", "d", "r", "_", "f")
+    assert str(astr) == "\\ar[dr]_{f}"
+
+    astr = ArrowStringDescription("cm", "", 12, "r", "u", "d", "r", "_", "f")
+    assert str(astr) == "\\ar@(r,u)[dr]_{f}"
+
+    astr = ArrowStringDescription("cm", "", 12, "r", "u", "d", "r", "_", "f")
+    assert str(astr) == "\\ar@(r,u)[dr]_{f}"
+
+    astr = ArrowStringDescription("cm", "", 12, "r", "u", "d", "r", "_", "f")
+    astr.arrow_style = "{-->}"
+    assert str(astr) == "\\ar@(r,u)@{-->}[dr]_{f}"
+
+    astr = ArrowStringDescription("cm", "_", 12, "", "", "d", "r", "_", "f")
+    astr.arrow_style = "{-->}"
+    assert str(astr) == "\\ar@/_12cm/@{-->}[dr]_{f}"
+
+
+def test_XypicDiagramDrawer_line():
+    # A linear diagram.
+    A = Object("A")
+    B = Object("B")
+    C = Object("C")
+    D = Object("D")
+    E = Object("E")
+
+    f = NamedMorphism(A, B, "f")
+    g = NamedMorphism(B, C, "g")
+    h = NamedMorphism(C, D, "h")
+    i = NamedMorphism(D, E, "i")
+    d = Diagram([f, g, h, i])
+    grid = DiagramGrid(d, layout="sequential")
+    drawer = XypicDiagramDrawer()
+    assert drawer.draw(d, grid) == "\\xymatrix{\n" \
+        "A \\ar[r]^{f} & B \\ar[r]^{g} & C \\ar[r]^{h} & D \\ar[r]^{i} & E \n" \
+        "}\n"
+
+    # The same diagram, transposed.
+    grid = DiagramGrid(d, layout="sequential", transpose=True)
+    drawer = XypicDiagramDrawer()
+    assert drawer.draw(d, grid) == "\\xymatrix{\n" \
+        "A \\ar[d]^{f} \\\\\n" \
+        "B \\ar[d]^{g} \\\\\n" \
+        "C \\ar[d]^{h} \\\\\n" \
+        "D \\ar[d]^{i} \\\\\n" \
+        "E \n" \
+        "}\n"
+
+
+def test_XypicDiagramDrawer_triangle():
+    # A triangle diagram.
+    A = Object("A")
+    B = Object("B")
+    C = Object("C")
+    f = NamedMorphism(A, B, "f")
+    g = NamedMorphism(B, C, "g")
+
+    d = Diagram([f, g], {g * f: "unique"})
+    grid = DiagramGrid(d)
+    drawer = XypicDiagramDrawer()
+    assert drawer.draw(d, grid) == "\\xymatrix{\n" \
+        "A \\ar[d]_{g\\circ f} \\ar[r]^{f} & B \\ar[ld]^{g} \\\\\n" \
+        "C & \n" \
+        "}\n"
+
+    # The same diagram, transposed.
+    grid = DiagramGrid(d, transpose=True)
+    drawer = XypicDiagramDrawer()
+    assert drawer.draw(d, grid) == "\\xymatrix{\n" \
+        "A \\ar[r]^{g\\circ f} \\ar[d]_{f} & C \\\\\n" \
+        "B \\ar[ru]_{g} & \n" \
+        "}\n"
+
+    # The same diagram, with a masked morphism.
+    assert drawer.draw(d, grid, masked=[g]) == "\\xymatrix{\n" \
+        "A \\ar[r]^{g\\circ f} \\ar[d]_{f} & C \\\\\n" \
+        "B & \n" \
+        "}\n"
+
+    # The same diagram with a formatter for "unique".
+    def formatter(astr):
+        astr.label = "\\exists !" + astr.label
+        astr.arrow_style = "{-->}"
+
+    drawer.arrow_formatters["unique"] = formatter
+    assert drawer.draw(d, grid) == "\\xymatrix{\n" \
+        "A \\ar@{-->}[r]^{\\exists !g\\circ f} \\ar[d]_{f} & C \\\\\n" \
+        "B \\ar[ru]_{g} & \n" \
+        "}\n"
+
+    # The same diagram with a default formatter.
+    def default_formatter(astr):
+        astr.label_displacement = "(0.45)"
+
+    drawer.default_arrow_formatter = default_formatter
+    assert drawer.draw(d, grid) == "\\xymatrix{\n" \
+        "A \\ar@{-->}[r]^(0.45){\\exists !g\\circ f} \\ar[d]_(0.45){f} & C \\\\\n" \
+        "B \\ar[ru]_(0.45){g} & \n" \
+        "}\n"
+
+    # A triangle diagram with a lot of morphisms between the same
+    # objects.
+    f1 = NamedMorphism(B, A, "f1")
+    f2 = NamedMorphism(A, B, "f2")
+    g1 = NamedMorphism(C, B, "g1")
+    g2 = NamedMorphism(B, C, "g2")
+    d = Diagram([f, f1, f2, g, g1, g2], {f1 * g1: "unique", g2 * f2: "unique"})
+
+    grid = DiagramGrid(d, transpose=True)
+    drawer = XypicDiagramDrawer()
+    assert drawer.draw(d, grid, masked=[f1*g1*g2*f2, g2*f2*f1*g1]) == \
+        "\\xymatrix{\n" \
+        "A \\ar[r]^{g_{2}\\circ f_{2}} \\ar[d]_{f} \\ar@/^3mm/[d]^{f_{2}} " \
+        "& C \\ar@/^3mm/[l]^{f_{1}\\circ g_{1}} \\ar@/^3mm/[ld]^{g_{1}} \\\\\n" \
+        "B \\ar@/^3mm/[u]^{f_{1}} \\ar[ru]_{g} \\ar@/^3mm/[ru]^{g_{2}} & \n" \
+        "}\n"
+
+
+def test_XypicDiagramDrawer_cube():
+    # A cube diagram.
+    A1 = Object("A1")
+    A2 = Object("A2")
+    A3 = Object("A3")
+    A4 = Object("A4")
+    A5 = Object("A5")
+    A6 = Object("A6")
+    A7 = Object("A7")
+    A8 = Object("A8")
+
+    # The top face of the cube.
+    f1 = NamedMorphism(A1, A2, "f1")
+    f2 = NamedMorphism(A1, A3, "f2")
+    f3 = NamedMorphism(A2, A4, "f3")
+    f4 = NamedMorphism(A3, A4, "f3")
+
+    # The bottom face of the cube.
+    f5 = NamedMorphism(A5, A6, "f5")
+    f6 = NamedMorphism(A5, A7, "f6")
+    f7 = NamedMorphism(A6, A8, "f7")
+    f8 = NamedMorphism(A7, A8, "f8")
+
+    # The remaining morphisms.
+    f9 = NamedMorphism(A1, A5, "f9")
+    f10 = NamedMorphism(A2, A6, "f10")
+    f11 = NamedMorphism(A3, A7, "f11")
+    f12 = NamedMorphism(A4, A8, "f11")
+
+    d = Diagram([f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11, f12])
+    grid = DiagramGrid(d)
+    drawer = XypicDiagramDrawer()
+    assert drawer.draw(d, grid) == "\\xymatrix{\n" \
+        "& A_{5} \\ar[r]^{f_{5}} \\ar[ldd]_{f_{6}} & A_{6} \\ar[rdd]^{f_{7}} " \
+        "& \\\\\n" \
+        "& A_{1} \\ar[r]^{f_{1}} \\ar[d]^{f_{2}} \\ar[u]^{f_{9}} & A_{2} " \
+        "\\ar[d]^{f_{3}} \\ar[u]_{f_{10}} & \\\\\n" \
+        "A_{7} \\ar@/_3mm/[rrr]_{f_{8}} & A_{3} \\ar[r]^{f_{3}} \\ar[l]_{f_{11}} " \
+        "& A_{4} \\ar[r]^{f_{11}} & A_{8} \n" \
+        "}\n"
+
+    # The same diagram, transposed.
+    grid = DiagramGrid(d, transpose=True)
+    drawer = XypicDiagramDrawer()
+    assert drawer.draw(d, grid) == "\\xymatrix{\n" \
+        "& & A_{7} \\ar@/^3mm/[ddd]^{f_{8}} \\\\\n" \
+        "A_{5} \\ar[d]_{f_{5}} \\ar[rru]^{f_{6}} & A_{1} \\ar[d]^{f_{1}} " \
+        "\\ar[r]^{f_{2}} \\ar[l]^{f_{9}} & A_{3} \\ar[d]_{f_{3}} " \
+        "\\ar[u]^{f_{11}} \\\\\n" \
+        "A_{6} \\ar[rrd]_{f_{7}} & A_{2} \\ar[r]^{f_{3}} \\ar[l]^{f_{10}} " \
+        "& A_{4} \\ar[d]_{f_{11}} \\\\\n" \
+        "& & A_{8} \n" \
+        "}\n"
+
+
+def test_XypicDiagramDrawer_curved_and_loops():
+    # A simple diagram, with a curved arrow.
+    A = Object("A")
+    B = Object("B")
+    C = Object("C")
+    D = Object("D")
+
+    f = NamedMorphism(A, B, "f")
+    g = NamedMorphism(B, C, "g")
+    h = NamedMorphism(D, A, "h")
+    k = NamedMorphism(D, B, "k")
+    d = Diagram([f, g, h, k])
+    grid = DiagramGrid(d)
+    drawer = XypicDiagramDrawer()
+    assert drawer.draw(d, grid) == "\\xymatrix{\n" \
+        "A \\ar[r]_{f} & B \\ar[d]^{g} & D \\ar[l]^{k} \\ar@/_3mm/[ll]_{h} \\\\\n" \
+        "& C & \n" \
+        "}\n"
+
+    # The same diagram, transposed.
+    grid = DiagramGrid(d, transpose=True)
+    drawer = XypicDiagramDrawer()
+    assert drawer.draw(d, grid) == "\\xymatrix{\n" \
+        "A \\ar[d]^{f} & \\\\\n" \
+        "B \\ar[r]^{g} & C \\\\\n" \
+        "D \\ar[u]_{k} \\ar@/^3mm/[uu]^{h} & \n" \
+        "}\n"
+
+    # The same diagram, larger and rotated.
+    assert drawer.draw(d, grid, diagram_format="@+1cm@dr") == \
+        "\\xymatrix@+1cm@dr{\n" \
+        "A \\ar[d]^{f} & \\\\\n" \
+        "B \\ar[r]^{g} & C \\\\\n" \
+        "D \\ar[u]_{k} \\ar@/^3mm/[uu]^{h} & \n" \
+        "}\n"
+
+    # A simple diagram with three curved arrows.
+    h1 = NamedMorphism(D, A, "h1")
+    h2 = NamedMorphism(A, D, "h2")
+    k = NamedMorphism(D, B, "k")
+    d = Diagram([f, g, h, k, h1, h2])
+    grid = DiagramGrid(d)
+    drawer = XypicDiagramDrawer()
+    assert drawer.draw(d, grid) == "\\xymatrix{\n" \
+        "A \\ar[r]_{f} \\ar@/^3mm/[rr]^{h_{2}} & B \\ar[d]^{g} & D \\ar[l]^{k} " \
+        "\\ar@/_7mm/[ll]_{h} \\ar@/_11mm/[ll]_{h_{1}} \\\\\n" \
+        "& C & \n" \
+        "}\n"
+
+    # The same diagram, transposed.
+    grid = DiagramGrid(d, transpose=True)
+    drawer = XypicDiagramDrawer()
+    assert drawer.draw(d, grid) == "\\xymatrix{\n" \
+        "A \\ar[d]^{f} \\ar@/_3mm/[dd]_{h_{2}} & \\\\\n" \
+        "B \\ar[r]^{g} & C \\\\\n" \
+        "D \\ar[u]_{k} \\ar@/^7mm/[uu]^{h} \\ar@/^11mm/[uu]^{h_{1}} & \n" \
+        "}\n"
+
+    # The same diagram, with "loop" morphisms.
+    l_A = NamedMorphism(A, A, "l_A")
+    l_D = NamedMorphism(D, D, "l_D")
+    l_C = NamedMorphism(C, C, "l_C")
+    d = Diagram([f, g, h, k, h1, h2, l_A, l_D, l_C])
+    grid = DiagramGrid(d)
+    drawer = XypicDiagramDrawer()
+    assert drawer.draw(d, grid) == "\\xymatrix{\n" \
+        "A \\ar[r]_{f} \\ar@/^3mm/[rr]^{h_{2}} \\ar@(u,l)[]^{l_{A}} " \
+        "& B \\ar[d]^{g} & D \\ar[l]^{k} \\ar@/_7mm/[ll]_{h} " \
+        "\\ar@/_11mm/[ll]_{h_{1}} \\ar@(r,u)[]^{l_{D}} \\\\\n" \
+        "& C \\ar@(l,d)[]^{l_{C}} & \n" \
+        "}\n"
+
+    # The same diagram with "loop" morphisms, transposed.
+    grid = DiagramGrid(d, transpose=True)
+    drawer = XypicDiagramDrawer()
+    assert drawer.draw(d, grid) == "\\xymatrix{\n" \
+        "A \\ar[d]^{f} \\ar@/_3mm/[dd]_{h_{2}} \\ar@(r,u)[]^{l_{A}} & \\\\\n" \
+        "B \\ar[r]^{g} & C \\ar@(r,u)[]^{l_{C}} \\\\\n" \
+        "D \\ar[u]_{k} \\ar@/^7mm/[uu]^{h} \\ar@/^11mm/[uu]^{h_{1}} " \
+        "\\ar@(l,d)[]^{l_{D}} & \n" \
+        "}\n"
+
+    # The same diagram with two "loop" morphisms per object.
+    l_A_ = NamedMorphism(A, A, "n_A")
+    l_D_ = NamedMorphism(D, D, "n_D")
+    l_C_ = NamedMorphism(C, C, "n_C")
+    d = Diagram([f, g, h, k, h1, h2, l_A, l_D, l_C, l_A_, l_D_, l_C_])
+    grid = DiagramGrid(d)
+    drawer = XypicDiagramDrawer()
+    assert drawer.draw(d, grid) == "\\xymatrix{\n" \
+        "A \\ar[r]_{f} \\ar@/^3mm/[rr]^{h_{2}} \\ar@(u,l)[]^{l_{A}} " \
+        "\\ar@/^3mm/@(l,d)[]^{n_{A}} & B \\ar[d]^{g} & D \\ar[l]^{k} " \
+        "\\ar@/_7mm/[ll]_{h} \\ar@/_11mm/[ll]_{h_{1}} \\ar@(r,u)[]^{l_{D}} " \
+        "\\ar@/^3mm/@(d,r)[]^{n_{D}} \\\\\n" \
+        "& C \\ar@(l,d)[]^{l_{C}} \\ar@/^3mm/@(d,r)[]^{n_{C}} & \n" \
+        "}\n"
+
+    # The same diagram with two "loop" morphisms per object, transposed.
+    grid = DiagramGrid(d, transpose=True)
+    drawer = XypicDiagramDrawer()
+    assert drawer.draw(d, grid) == "\\xymatrix{\n" \
+        "A \\ar[d]^{f} \\ar@/_3mm/[dd]_{h_{2}} \\ar@(r,u)[]^{l_{A}} " \
+        "\\ar@/^3mm/@(u,l)[]^{n_{A}} & \\\\\n" \
+        "B \\ar[r]^{g} & C \\ar@(r,u)[]^{l_{C}} \\ar@/^3mm/@(d,r)[]^{n_{C}} \\\\\n" \
+        "D \\ar[u]_{k} \\ar@/^7mm/[uu]^{h} \\ar@/^11mm/[uu]^{h_{1}} " \
+        "\\ar@(l,d)[]^{l_{D}} \\ar@/^3mm/@(d,r)[]^{n_{D}} & \n" \
+        "}\n"
+
+
+def test_xypic_draw_diagram():
+    # A linear diagram.
+    A = Object("A")
+    B = Object("B")
+    C = Object("C")
+    D = Object("D")
+    E = Object("E")
+
+    f = NamedMorphism(A, B, "f")
+    g = NamedMorphism(B, C, "g")
+    h = NamedMorphism(C, D, "h")
+    i = NamedMorphism(D, E, "i")
+    d = Diagram([f, g, h, i])
+
+    grid = DiagramGrid(d, layout="sequential")
+    drawer = XypicDiagramDrawer()
+    assert drawer.draw(d, grid) == xypic_draw_diagram(d, layout="sequential")

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

@@ -0,0 +1,19 @@
+from .diffgeom import (
+    BaseCovarDerivativeOp, BaseScalarField, BaseVectorField, Commutator,
+    contravariant_order, CoordSystem, CoordinateSymbol,
+    CovarDerivativeOp, covariant_order, Differential, intcurve_diffequ,
+    intcurve_series, LieDerivative, Manifold, metric_to_Christoffel_1st,
+    metric_to_Christoffel_2nd, metric_to_Ricci_components,
+    metric_to_Riemann_components, Patch, Point, TensorProduct, twoform_to_matrix,
+    vectors_in_basis, WedgeProduct,
+)
+
+__all__ = [
+    'BaseCovarDerivativeOp', 'BaseScalarField', 'BaseVectorField', 'Commutator',
+    'contravariant_order', 'CoordSystem', 'CoordinateSymbol',
+    'CovarDerivativeOp', 'covariant_order', 'Differential', 'intcurve_diffequ',
+    'intcurve_series', 'LieDerivative', 'Manifold', 'metric_to_Christoffel_1st',
+    'metric_to_Christoffel_2nd', 'metric_to_Ricci_components',
+    'metric_to_Riemann_components', 'Patch', 'Point', 'TensorProduct',
+    'twoform_to_matrix', 'vectors_in_basis', 'WedgeProduct',
+]

.venv/lib/python3.13/site-packages/sympy/diffgeom/diffgeom.py

@@ -0,0 +1,2270 @@
+from __future__ import annotations
+from typing import Any
+
+from functools import reduce
+from itertools import permutations
+
+from sympy.combinatorics import Permutation
+from sympy.core import (
+    Basic, Expr, Function, diff,
+    Pow, Mul, Add, Lambda, S, Tuple, Dict
+)
+from sympy.core.cache import cacheit
+
+from sympy.core.symbol import Symbol, Dummy
+from sympy.core.symbol import Str
+from sympy.core.sympify import _sympify
+from sympy.functions import factorial
+from sympy.matrices import ImmutableDenseMatrix as Matrix
+from sympy.solvers import solve
+
+from sympy.utilities.exceptions import (sympy_deprecation_warning,
+                                        SymPyDeprecationWarning,
+                                        ignore_warnings)
+
+
+# TODO you are a bit excessive in the use of Dummies
+# TODO dummy point, literal field
+# TODO too often one needs to call doit or simplify on the output, check the
+# tests and find out why
+from sympy.tensor.array import ImmutableDenseNDimArray
+
+
+class Manifold(Basic):
+    """
+    A mathematical manifold.
+
+    Explanation
+    ===========
+
+    A manifold is a topological space that locally resembles
+    Euclidean space near each point [1].
+    This class does not provide any means to study the topological
+    characteristics of the manifold that it represents, though.
+
+    Parameters
+    ==========
+
+    name : str
+        The name of the manifold.
+
+    dim : int
+        The dimension of the manifold.
+
+    Examples
+    ========
+
+    >>> from sympy.diffgeom import Manifold
+    >>> m = Manifold('M', 2)
+    >>> m
+    M
+    >>> m.dim
+    2
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Manifold
+    """
+
+    def __new__(cls, name, dim, **kwargs):
+        if not isinstance(name, Str):
+            name = Str(name)
+        dim = _sympify(dim)
+        obj = super().__new__(cls, name, dim)
+
+        obj.patches = _deprecated_list(
+            """
+            Manifold.patches is deprecated. The Manifold object is now
+            immutable. Instead use a separate list to keep track of the
+            patches.
+            """, [])
+        return obj
+
+    @property
+    def name(self):
+        return self.args[0]
+
+    @property
+    def dim(self):
+        return self.args[1]
+
+
+class Patch(Basic):
+    """
+    A patch on a manifold.
+
+    Explanation
+    ===========
+
+    Coordinate patch, or patch in short, is a simply-connected open set around
+    a point in the manifold [1]. On a manifold one can have many patches that
+    do not always include the whole manifold. On these patches coordinate
+    charts can be defined that permit the parameterization of any point on the
+    patch in terms of a tuple of real numbers (the coordinates).
+
+    This class does not provide any means to study the topological
+    characteristics of the patch that it represents.
+
+    Parameters
+    ==========
+
+    name : str
+        The name of the patch.
+
+    manifold : Manifold
+        The manifold on which the patch is defined.
+
+    Examples
+    ========
+
+    >>> from sympy.diffgeom import Manifold, Patch
+    >>> m = Manifold('M', 2)
+    >>> p = Patch('P', m)
+    >>> p
+    P
+    >>> p.dim
+    2
+
+    References
+    ==========
+
+    .. [1] G. Sussman, J. Wisdom, W. Farr, Functional Differential Geometry
+           (2013)
+
+    """
+    def __new__(cls, name, manifold, **kwargs):
+        if not isinstance(name, Str):
+            name = Str(name)
+        obj = super().__new__(cls, name, manifold)
+
+        obj.manifold.patches.append(obj) # deprecated
+        obj.coord_systems = _deprecated_list(
+            """
+            Patch.coord_systms is deprecated. The Patch class is now
+            immutable. Instead use a separate list to keep track of coordinate
+            systems.
+            """, [])
+        return obj
+
+    @property
+    def name(self):
+        return self.args[0]
+
+    @property
+    def manifold(self):
+        return self.args[1]
+
+    @property
+    def dim(self):
+        return self.manifold.dim
+
+
+class CoordSystem(Basic):
+    """
+    A coordinate system defined on the patch.
+
+    Explanation
+    ===========
+
+    Coordinate system is a system that uses one or more coordinates to uniquely
+    determine the position of the points or other geometric elements on a
+    manifold [1].
+
+    By passing ``Symbols`` to *symbols* parameter, user can define the name and
+    assumptions of coordinate symbols of the coordinate system. If not passed,
+    these symbols are generated automatically and are assumed to be real valued.
+
+    By passing *relations* parameter, user can define the transform relations of
+    coordinate systems. Inverse transformation and indirect transformation can
+    be found automatically. If this parameter is not passed, coordinate
+    transformation cannot be done.
+
+    Parameters
+    ==========
+
+    name : str
+        The name of the coordinate system.
+
+    patch : Patch
+        The patch where the coordinate system is defined.
+
+    symbols : list of Symbols, optional
+        Defines the names and assumptions of coordinate symbols.
+
+    relations : dict, optional
+        Key is a tuple of two strings, who are the names of the systems where
+        the coordinates transform from and transform to.
+        Value is a tuple of the symbols before transformation and a tuple of
+        the expressions after transformation.
+
+    Examples
+    ========
+
+    We define two-dimensional Cartesian coordinate system and polar coordinate
+    system.
+
+    >>> from sympy import symbols, pi, sqrt, atan2, cos, sin
+    >>> from sympy.diffgeom import Manifold, Patch, CoordSystem
+    >>> m = Manifold('M', 2)
+    >>> p = Patch('P', m)
+    >>> x, y = symbols('x y', real=True)
+    >>> r, theta = symbols('r theta', nonnegative=True)
+    >>> relation_dict = {
+    ... ('Car2D', 'Pol'): [(x, y), (sqrt(x**2 + y**2), atan2(y, x))],
+    ... ('Pol', 'Car2D'): [(r, theta), (r*cos(theta), r*sin(theta))]
+    ... }
+    >>> Car2D = CoordSystem('Car2D', p, (x, y), relation_dict)
+    >>> Pol = CoordSystem('Pol', p, (r, theta), relation_dict)
+
+    ``symbols`` property returns ``CoordinateSymbol`` instances. These symbols
+    are not same with the symbols used to construct the coordinate system.
+
+    >>> Car2D
+    Car2D
+    >>> Car2D.dim
+    2
+    >>> Car2D.symbols
+    (x, y)
+    >>> _[0].func
+    <class 'sympy.diffgeom.diffgeom.CoordinateSymbol'>
+
+    ``transformation()`` method returns the transformation function from
+    one coordinate system to another. ``transform()`` method returns the
+    transformed coordinates.
+
+    >>> Car2D.transformation(Pol)
+    Lambda((x, y), Matrix([
+    [sqrt(x**2 + y**2)],
+    [      atan2(y, x)]]))
+    >>> Car2D.transform(Pol)
+    Matrix([
+    [sqrt(x**2 + y**2)],
+    [      atan2(y, x)]])
+    >>> Car2D.transform(Pol, [1, 2])
+    Matrix([
+    [sqrt(5)],
+    [atan(2)]])
+
+    ``jacobian()`` method returns the Jacobian matrix of coordinate
+    transformation between two systems. ``jacobian_determinant()`` method
+    returns the Jacobian determinant of coordinate transformation between two
+    systems.
+
+    >>> Pol.jacobian(Car2D)
+    Matrix([
+    [cos(theta), -r*sin(theta)],
+    [sin(theta),  r*cos(theta)]])
+    >>> Pol.jacobian(Car2D, [1, pi/2])
+    Matrix([
+    [0, -1],
+    [1,  0]])
+    >>> Car2D.jacobian_determinant(Pol)
+    1/sqrt(x**2 + y**2)
+    >>> Car2D.jacobian_determinant(Pol, [1,0])
+    1
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Coordinate_system
+
+    """
+    def __new__(cls, name, patch, symbols=None, relations={}, **kwargs):
+        if not isinstance(name, Str):
+            name = Str(name)
+
+        # canonicallize the symbols
+        if symbols is None:
+            names = kwargs.get('names', None)
+            if names is None:
+                symbols = Tuple(
+                    *[Symbol('%s_%s' % (name.name, i), real=True)
+                      for i in range(patch.dim)]
+                )
+            else:
+                sympy_deprecation_warning(
+                    f"""
+The 'names' argument to CoordSystem is deprecated. Use 'symbols' instead. That
+is, replace
+
+    CoordSystem(..., names={names})
+
+with
+
+    CoordSystem(..., symbols=[{', '.join(["Symbol(" + repr(n) + ", real=True)" for n in names])}])
+                    """,
+                    deprecated_since_version="1.7",
+                    active_deprecations_target="deprecated-diffgeom-mutable",
+                )
+                symbols = Tuple(
+                    *[Symbol(n, real=True) for n in names]
+                )
+        else:
+            syms = []
+            for s in symbols:
+                if isinstance(s, Symbol):
+                    syms.append(Symbol(s.name, **s._assumptions.generator))
+                elif isinstance(s, str):
+                    sympy_deprecation_warning(
+                        f"""
+
+Passing a string as the coordinate symbol name to CoordSystem is deprecated.
+Pass a Symbol with the appropriate name and assumptions instead.
+
+That is, replace {s} with Symbol({s!r}, real=True).
+                        """,
+
+                        deprecated_since_version="1.7",
+                        active_deprecations_target="deprecated-diffgeom-mutable",
+                    )
+                    syms.append(Symbol(s, real=True))
+            symbols = Tuple(*syms)
+
+        # canonicallize the relations
+        rel_temp = {}
+        for k,v in relations.items():
+            s1, s2 = k
+            if not isinstance(s1, Str):
+                s1 = Str(s1)
+            if not isinstance(s2, Str):
+                s2 = Str(s2)
+            key = Tuple(s1, s2)
+
+            # Old version used Lambda as a value.
+            if isinstance(v, Lambda):
+                v = (tuple(v.signature), tuple(v.expr))
+            else:
+                v = (tuple(v[0]), tuple(v[1]))
+            rel_temp[key] = v
+        relations = Dict(rel_temp)
+
+        # construct the object
+        obj = super().__new__(cls, name, patch, symbols, relations)
+
+        # Add deprecated attributes
+        obj.transforms = _deprecated_dict(
+            """
+            CoordSystem.transforms is deprecated. The CoordSystem class is now
+            immutable. Use the 'relations' keyword argument to the
+            CoordSystems() constructor to specify relations.
+            """, {})
+        obj._names = [str(n) for n in symbols]
+        obj.patch.coord_systems.append(obj) # deprecated
+        obj._dummies = [Dummy(str(n)) for n in symbols] # deprecated
+        obj._dummy = Dummy()
+
+        return obj
+
+    @property
+    def name(self):
+        return self.args[0]
+
+    @property
+    def patch(self):
+        return self.args[1]
+
+    @property
+    def manifold(self):
+        return self.patch.manifold
+
+    @property
+    def symbols(self):
+        return tuple(CoordinateSymbol(self, i, **s._assumptions.generator)
+            for i,s in enumerate(self.args[2]))
+
+    @property
+    def relations(self):
+        return self.args[3]
+
+    @property
+    def dim(self):
+        return self.patch.dim
+
+    ##########################################################################
+    # Finding transformation relation
+    ##########################################################################
+
+    def transformation(self, sys):
+        """
+        Return coordinate transformation function from *self* to *sys*.
+
+        Parameters
+        ==========
+
+        sys : CoordSystem
+
+        Returns
+        =======
+
+        sympy.Lambda
+
+        Examples
+        ========
+
+        >>> from sympy.diffgeom.rn import R2_r, R2_p
+        >>> R2_r.transformation(R2_p)
+        Lambda((x, y), Matrix([
+        [sqrt(x**2 + y**2)],
+        [      atan2(y, x)]]))
+
+        """
+        signature = self.args[2]
+
+        key = Tuple(self.name, sys.name)
+        if self == sys:
+            expr = Matrix(self.symbols)
+        elif key in self.relations:
+            expr = Matrix(self.relations[key][1])
+        elif key[::-1] in self.relations:
+            expr = Matrix(self._inverse_transformation(sys, self))
+        else:
+            expr = Matrix(self._indirect_transformation(self, sys))
+        return Lambda(signature, expr)
+
+    @staticmethod
+    def _solve_inverse(sym1, sym2, exprs, sys1_name, sys2_name):
+        ret = solve(
+            [t[0] - t[1] for t in zip(sym2, exprs)],
+            list(sym1), dict=True)
+
+        if len(ret) == 0:
+            temp = "Cannot solve inverse relation from {} to {}."
+            raise NotImplementedError(temp.format(sys1_name, sys2_name))
+        elif len(ret) > 1:
+            temp = "Obtained multiple inverse relation from {} to {}."
+            raise ValueError(temp.format(sys1_name, sys2_name))
+
+        return ret[0]
+
+    @classmethod
+    def _inverse_transformation(cls, sys1, sys2):
+        # Find the transformation relation from sys2 to sys1
+        forward = sys1.transform(sys2)
+        inv_results = cls._solve_inverse(sys1.symbols, sys2.symbols, forward,
+                                         sys1.name, sys2.name)
+        signature = tuple(sys1.symbols)
+        return [inv_results[s] for s in signature]
+
+    @classmethod
+    @cacheit
+    def _indirect_transformation(cls, sys1, sys2):
+        # Find the transformation relation between two indirectly connected
+        # coordinate systems
+        rel = sys1.relations
+        path = cls._dijkstra(sys1, sys2)
+
+        transforms = []
+        for s1, s2 in zip(path, path[1:]):
+            if (s1, s2) in rel:
+                transforms.append(rel[(s1, s2)])
+            else:
+                sym2, inv_exprs = rel[(s2, s1)]
+                sym1 = tuple(Dummy() for i in sym2)
+                ret = cls._solve_inverse(sym2, sym1, inv_exprs, s2, s1)
+                ret = tuple(ret[s] for s in sym2)
+                transforms.append((sym1, ret))
+        syms = sys1.args[2]
+        exprs = syms
+        for newsyms, newexprs in transforms:
+            exprs = tuple(e.subs(zip(newsyms, exprs)) for e in newexprs)
+        return exprs
+
+    @staticmethod
+    def _dijkstra(sys1, sys2):
+        # Use Dijkstra algorithm to find the shortest path between two indirectly-connected
+        # coordinate systems
+        # return value is the list of the names of the systems.
+        relations = sys1.relations
+        graph = {}
+        for s1, s2 in relations.keys():
+            if s1 not in graph:
+                graph[s1] = {s2}
+            else:
+                graph[s1].add(s2)
+            if s2 not in graph:
+                graph[s2] = {s1}
+            else:
+                graph[s2].add(s1)
+
+        path_dict = {sys:[0, [], 0] for sys in graph} # minimum distance, path, times of visited
+
+        def visit(sys):
+            path_dict[sys][2] = 1
+            for newsys in graph[sys]:
+                distance = path_dict[sys][0] + 1
+                if path_dict[newsys][0] >= distance or not path_dict[newsys][1]:
+                    path_dict[newsys][0] = distance
+                    path_dict[newsys][1] = list(path_dict[sys][1])
+                    path_dict[newsys][1].append(sys)
+
+        visit(sys1.name)
+
+        while True:
+            min_distance = max(path_dict.values(), key=lambda x:x[0])[0]
+            newsys = None
+            for sys, lst in path_dict.items():
+                if 0 < lst[0] <= min_distance and not lst[2]:
+                    min_distance = lst[0]
+                    newsys = sys
+            if newsys is None:
+                break
+            visit(newsys)
+
+        result = path_dict[sys2.name][1]
+        result.append(sys2.name)
+
+        if result == [sys2.name]:
+            raise KeyError("Two coordinate systems are not connected.")
+        return result
+
+    def connect_to(self, to_sys, from_coords, to_exprs, inverse=True, fill_in_gaps=False):
+        sympy_deprecation_warning(
+            """
+            The CoordSystem.connect_to() method is deprecated. Instead,
+            generate a new instance of CoordSystem with the 'relations'
+            keyword argument (CoordSystem classes are now immutable).
+            """,
+            deprecated_since_version="1.7",
+            active_deprecations_target="deprecated-diffgeom-mutable",
+        )
+
+        from_coords, to_exprs = dummyfy(from_coords, to_exprs)
+        self.transforms[to_sys] = Matrix(from_coords), Matrix(to_exprs)
+
+        if inverse:
+            to_sys.transforms[self] = self._inv_transf(from_coords, to_exprs)
+
+        if fill_in_gaps:
+            self._fill_gaps_in_transformations()
+
+    @staticmethod
+    def _inv_transf(from_coords, to_exprs):
+        # Will be removed when connect_to is removed
+        inv_from = [i.as_dummy() for i in from_coords]
+        inv_to = solve(
+            [t[0] - t[1] for t in zip(inv_from, to_exprs)],
+            list(from_coords), dict=True)[0]
+        inv_to = [inv_to[fc] for fc in from_coords]
+        return Matrix(inv_from), Matrix(inv_to)
+
+    @staticmethod
+    def _fill_gaps_in_transformations():
+        # Will be removed when connect_to is removed
+        raise NotImplementedError
+
+    ##########################################################################
+    # Coordinate transformations
+    ##########################################################################
+
+    def transform(self, sys, coordinates=None):
+        """
+        Return the result of coordinate transformation from *self* to *sys*.
+        If coordinates are not given, coordinate symbols of *self* are used.
+
+        Parameters
+        ==========
+
+        sys : CoordSystem
+
+        coordinates : Any iterable, optional.
+
+        Returns
+        =======
+
+        sympy.ImmutableDenseMatrix containing CoordinateSymbol
+
+        Examples
+        ========
+
+        >>> from sympy.diffgeom.rn import R2_r, R2_p
+        >>> R2_r.transform(R2_p)
+        Matrix([
+        [sqrt(x**2 + y**2)],
+        [      atan2(y, x)]])
+        >>> R2_r.transform(R2_p, [0, 1])
+        Matrix([
+        [   1],
+        [pi/2]])
+
+        """
+        if coordinates is None:
+            coordinates = self.symbols
+        if self != sys:
+            transf = self.transformation(sys)
+            coordinates = transf(*coordinates)
+        else:
+            coordinates = Matrix(coordinates)
+        return coordinates
+
+    def coord_tuple_transform_to(self, to_sys, coords):
+        """Transform ``coords`` to coord system ``to_sys``."""
+        sympy_deprecation_warning(
+            """
+            The CoordSystem.coord_tuple_transform_to() method is deprecated.
+            Use the CoordSystem.transform() method instead.
+            """,
+            deprecated_since_version="1.7",
+            active_deprecations_target="deprecated-diffgeom-mutable",
+        )
+
+        coords = Matrix(coords)
+        if self != to_sys:
+            with ignore_warnings(SymPyDeprecationWarning):
+                transf = self.transforms[to_sys]
+            coords = transf[1].subs(list(zip(transf[0], coords)))
+        return coords
+
+    def jacobian(self, sys, coordinates=None):
+        """
+        Return the jacobian matrix of a transformation on given coordinates.
+        If coordinates are not given, coordinate symbols of *self* are used.
+
+        Parameters
+        ==========
+
+        sys : CoordSystem
+
+        coordinates : Any iterable, optional.
+
+        Returns
+        =======
+
+        sympy.ImmutableDenseMatrix
+
+        Examples
+        ========
+
+        >>> from sympy.diffgeom.rn import R2_r, R2_p
+        >>> R2_p.jacobian(R2_r)
+        Matrix([
+        [cos(theta), -rho*sin(theta)],
+        [sin(theta),  rho*cos(theta)]])
+        >>> R2_p.jacobian(R2_r, [1, 0])
+        Matrix([
+        [1, 0],
+        [0, 1]])
+
+        """
+        result = self.transform(sys).jacobian(self.symbols)
+        if coordinates is not None:
+            result = result.subs(list(zip(self.symbols, coordinates)))
+        return result
+    jacobian_matrix = jacobian
+
+    def jacobian_determinant(self, sys, coordinates=None):
+        """
+        Return the jacobian determinant of a transformation on given
+        coordinates. If coordinates are not given, coordinate symbols of *self*
+        are used.
+
+        Parameters
+        ==========
+
+        sys : CoordSystem
+
+        coordinates : Any iterable, optional.
+
+        Returns
+        =======
+
+        sympy.Expr
+
+        Examples
+        ========
+
+        >>> from sympy.diffgeom.rn import R2_r, R2_p
+        >>> R2_r.jacobian_determinant(R2_p)
+        1/sqrt(x**2 + y**2)
+        >>> R2_r.jacobian_determinant(R2_p, [1, 0])
+        1
+
+        """
+        return self.jacobian(sys, coordinates).det()
+
+
+    ##########################################################################
+    # Points
+    ##########################################################################
+
+    def point(self, coords):
+        """Create a ``Point`` with coordinates given in this coord system."""
+        return Point(self, coords)
+
+    def point_to_coords(self, point):
+        """Calculate the coordinates of a point in this coord system."""
+        return point.coords(self)
+
+    ##########################################################################
+    # Base fields.
+    ##########################################################################
+
+    def base_scalar(self, coord_index):
+        """Return ``BaseScalarField`` that takes a point and returns one of the coordinates."""
+        return BaseScalarField(self, coord_index)
+    coord_function = base_scalar
+
+    def base_scalars(self):
+        """Returns a list of all coordinate functions.
+        For more details see the ``base_scalar`` method of this class."""
+        return [self.base_scalar(i) for i in range(self.dim)]
+    coord_functions = base_scalars
+
+    def base_vector(self, coord_index):
+        """Return a basis vector field.
+        The basis vector field for this coordinate system. It is also an
+        operator on scalar fields."""
+        return BaseVectorField(self, coord_index)
+
+    def base_vectors(self):
+        """Returns a list of all base vectors.
+        For more details see the ``base_vector`` method of this class."""
+        return [self.base_vector(i) for i in range(self.dim)]
+
+    def base_oneform(self, coord_index):
+        """Return a basis 1-form field.
+        The basis one-form field for this coordinate system. It is also an
+        operator on vector fields."""
+        return Differential(self.coord_function(coord_index))
+
+    def base_oneforms(self):
+        """Returns a list of all base oneforms.
+        For more details see the ``base_oneform`` method of this class."""
+        return [self.base_oneform(i) for i in range(self.dim)]
+
+
+class CoordinateSymbol(Symbol):
+    """A symbol which denotes an abstract value of i-th coordinate of
+    the coordinate system with given context.
+
+    Explanation
+    ===========
+
+    Each coordinates in coordinate system are represented by unique symbol,
+    such as x, y, z in Cartesian coordinate system.
+
+    You may not construct this class directly. Instead, use `symbols` method
+    of CoordSystem.
+
+    Parameters
+    ==========
+
+    coord_sys : CoordSystem
+
+    index : integer
+
+    Examples
+    ========
+
+    >>> from sympy import symbols, Lambda, Matrix, sqrt, atan2, cos, sin
+    >>> from sympy.diffgeom import Manifold, Patch, CoordSystem
+    >>> m = Manifold('M', 2)
+    >>> p = Patch('P', m)
+    >>> x, y = symbols('x y', real=True)
+    >>> r, theta = symbols('r theta', nonnegative=True)
+    >>> relation_dict = {
+    ... ('Car2D', 'Pol'): Lambda((x, y), Matrix([sqrt(x**2 + y**2), atan2(y, x)])),
+    ... ('Pol', 'Car2D'): Lambda((r, theta), Matrix([r*cos(theta), r*sin(theta)]))
+    ... }
+    >>> Car2D = CoordSystem('Car2D', p, [x, y], relation_dict)
+    >>> Pol = CoordSystem('Pol', p, [r, theta], relation_dict)
+    >>> x, y = Car2D.symbols
+
+    ``CoordinateSymbol`` contains its coordinate symbol and index.
+
+    >>> x.name
+    'x'
+    >>> x.coord_sys == Car2D
+    True
+    >>> x.index
+    0
+    >>> x.is_real
+    True
+
+    You can transform ``CoordinateSymbol`` into other coordinate system using
+    ``rewrite()`` method.
+
+    >>> x.rewrite(Pol)
+    r*cos(theta)
+    >>> sqrt(x**2 + y**2).rewrite(Pol).simplify()
+    r
+
+    """
+    def __new__(cls, coord_sys, index, **assumptions):
+        name = coord_sys.args[2][index].name
+        obj = super().__new__(cls, name, **assumptions)
+        obj.coord_sys = coord_sys
+        obj.index = index
+        return obj
+
+    def __getnewargs__(self):
+        return (self.coord_sys, self.index)
+
+    def _hashable_content(self):
+        return (
+            self.coord_sys, self.index
+        ) + tuple(sorted(self.assumptions0.items()))
+
+    def _eval_rewrite(self, rule, args, **hints):
+        if isinstance(rule, CoordSystem):
+            return rule.transform(self.coord_sys)[self.index]
+        return super()._eval_rewrite(rule, args, **hints)
+
+
+class Point(Basic):
+    """Point defined in a coordinate system.
+
+    Explanation
+    ===========
+
+    Mathematically, point is defined in the manifold and does not have any coordinates
+    by itself. Coordinate system is what imbues the coordinates to the point by coordinate
+    chart. However, due to the difficulty of realizing such logic, you must supply
+    a coordinate system and coordinates to define a Point here.
+
+    The usage of this object after its definition is independent of the
+    coordinate system that was used in order to define it, however due to
+    limitations in the simplification routines you can arrive at complicated
+    expressions if you use inappropriate coordinate systems.
+
+    Parameters
+    ==========
+
+    coord_sys : CoordSystem
+
+    coords : list
+        The coordinates of the point.
+
+    Examples
+    ========
+
+    >>> from sympy import pi
+    >>> from sympy.diffgeom import Point
+    >>> from sympy.diffgeom.rn import R2, R2_r, R2_p
+    >>> rho, theta = R2_p.symbols
+
+    >>> p = Point(R2_p, [rho, 3*pi/4])
+
+    >>> p.manifold == R2
+    True
+
+    >>> p.coords()
+    Matrix([
+    [   rho],
+    [3*pi/4]])
+    >>> p.coords(R2_r)
+    Matrix([
+    [-sqrt(2)*rho/2],
+    [ sqrt(2)*rho/2]])
+
+    """
+
+    def __new__(cls, coord_sys, coords, **kwargs):
+        coords = Matrix(coords)
+        obj = super().__new__(cls, coord_sys, coords)
+        obj._coord_sys = coord_sys
+        obj._coords = coords
+        return obj
+
+    @property
+    def patch(self):
+        return self._coord_sys.patch
+
+    @property
+    def manifold(self):
+        return self._coord_sys.manifold
+
+    @property
+    def dim(self):
+        return self.manifold.dim
+
+    def coords(self, sys=None):
+        """
+        Coordinates of the point in given coordinate system. If coordinate system
+        is not passed, it returns the coordinates in the coordinate system in which
+        the point was defined.
+        """
+        if sys is None:
+            return self._coords
+        else:
+            return self._coord_sys.transform(sys, self._coords)
+
+    @property
+    def free_symbols(self):
+        return self._coords.free_symbols
+
+
+class BaseScalarField(Expr):
+    """Base scalar field over a manifold for a given coordinate system.
+
+    Explanation
+    ===========
+
+    A scalar field takes a point as an argument and returns a scalar.
+    A base scalar field of a coordinate system takes a point and returns one of
+    the coordinates of that point in the coordinate system in question.
+
+    To define a scalar field you need to choose the coordinate system and the
+    index of the coordinate.
+
+    The use of the scalar field after its definition is independent of the
+    coordinate system in which it was defined, however due to limitations in
+    the simplification routines you may arrive at more complicated
+    expression if you use unappropriate coordinate systems.
+    You can build complicated scalar fields by just building up SymPy
+    expressions containing ``BaseScalarField`` instances.
+
+    Parameters
+    ==========
+
+    coord_sys : CoordSystem
+
+    index : integer
+
+    Examples
+    ========
+
+    >>> from sympy import Function, pi
+    >>> from sympy.diffgeom import BaseScalarField
+    >>> from sympy.diffgeom.rn import R2_r, R2_p
+    >>> rho, _ = R2_p.symbols
+    >>> point = R2_p.point([rho, 0])
+    >>> fx, fy = R2_r.base_scalars()
+    >>> ftheta = BaseScalarField(R2_r, 1)
+
+    >>> fx(point)
+    rho
+    >>> fy(point)
+    0
+
+    >>> (fx**2+fy**2).rcall(point)
+    rho**2
+
+    >>> g = Function('g')
+    >>> fg = g(ftheta-pi)
+    >>> fg.rcall(point)
+    g(-pi)
+
+    """
+
+    is_commutative = True
+
+    def __new__(cls, coord_sys, index, **kwargs):
+        index = _sympify(index)
+        obj = super().__new__(cls, coord_sys, index)
+        obj._coord_sys = coord_sys
+        obj._index = index
+        return obj
+
+    @property
+    def coord_sys(self):
+        return self.args[0]
+
+    @property
+    def index(self):
+        return self.args[1]
+
+    @property
+    def patch(self):
+        return self.coord_sys.patch
+
+    @property
+    def manifold(self):
+        return self.coord_sys.manifold
+
+    @property
+    def dim(self):
+        return self.manifold.dim
+
+    def __call__(self, *args):
+        """Evaluating the field at a point or doing nothing.
+        If the argument is a ``Point`` instance, the field is evaluated at that
+        point. The field is returned itself if the argument is any other
+        object. It is so in order to have working recursive calling mechanics
+        for all fields (check the ``__call__`` method of ``Expr``).
+        """
+        point = args[0]
+        if len(args) != 1 or not isinstance(point, Point):
+            return self
+        coords = point.coords(self._coord_sys)
+        # XXX Calling doit  is necessary with all the Subs expressions
+        # XXX Calling simplify is necessary with all the trig expressions
+        return simplify(coords[self._index]).doit()
+
+    # XXX Workaround for limitations on the content of args
+    free_symbols: set[Any] = set()
+
+
+class BaseVectorField(Expr):
+    r"""Base vector field over a manifold for a given coordinate system.
+
+    Explanation
+    ===========
+
+    A vector field is an operator taking a scalar field and returning a
+    directional derivative (which is also a scalar field).
+    A base vector field is the same type of operator, however the derivation is
+    specifically done with respect to a chosen coordinate.
+
+    To define a base vector field you need to choose the coordinate system and
+    the index of the coordinate.
+
+    The use of the vector field after its definition is independent of the
+    coordinate system in which it was defined, however due to limitations in the
+    simplification routines you may arrive at more complicated expression if you
+    use unappropriate coordinate systems.
+
+    Parameters
+    ==========
+    coord_sys : CoordSystem
+
+    index : integer
+
+    Examples
+    ========
+
+    >>> from sympy import Function
+    >>> from sympy.diffgeom.rn import R2_p, R2_r
+    >>> from sympy.diffgeom import BaseVectorField
+    >>> from sympy import pprint
+
+    >>> x, y = R2_r.symbols
+    >>> rho, theta = R2_p.symbols
+    >>> fx, fy = R2_r.base_scalars()
+    >>> point_p = R2_p.point([rho, theta])
+    >>> point_r = R2_r.point([x, y])
+
+    >>> g = Function('g')
+    >>> s_field = g(fx, fy)
+
+    >>> v = BaseVectorField(R2_r, 1)
+    >>> pprint(v(s_field))
+    / d           \|
+    |---(g(x, xi))||
+    \dxi          /|xi=y
+    >>> pprint(v(s_field).rcall(point_r).doit())
+    d
+    --(g(x, y))
+    dy
+    >>> pprint(v(s_field).rcall(point_p))
+    / d                        \|
+    |---(g(rho*cos(theta), xi))||
+    \dxi                       /|xi=rho*sin(theta)
+
+    """
+
+    is_commutative = False
+
+    def __new__(cls, coord_sys, index, **kwargs):
+        index = _sympify(index)
+        obj = super().__new__(cls, coord_sys, index)
+        obj._coord_sys = coord_sys
+        obj._index = index
+        return obj
+
+    @property
+    def coord_sys(self):
+        return self.args[0]
+
+    @property
+    def index(self):
+        return self.args[1]
+
+    @property
+    def patch(self):
+        return self.coord_sys.patch
+
+    @property
+    def manifold(self):
+        return self.coord_sys.manifold
+
+    @property
+    def dim(self):
+        return self.manifold.dim
+
+    def __call__(self, scalar_field):
+        """Apply on a scalar field.
+        The action of a vector field on a scalar field is a directional
+        differentiation.
+        If the argument is not a scalar field an error is raised.
+        """
+        if covariant_order(scalar_field) or contravariant_order(scalar_field):
+            raise ValueError('Only scalar fields can be supplied as arguments to vector fields.')
+
+        if scalar_field is None:
+            return self
+
+        base_scalars = list(scalar_field.atoms(BaseScalarField))
+
+        # First step: e_x(x+r**2) -> e_x(x) + 2*r*e_x(r)
+        d_var = self._coord_sys._dummy
+        # TODO: you need a real dummy function for the next line
+        d_funcs = [Function('_#_%s' % i)(d_var) for i,
+                   b in enumerate(base_scalars)]
+        d_result = scalar_field.subs(list(zip(base_scalars, d_funcs)))
+        d_result = d_result.diff(d_var)
+
+        # Second step: e_x(x) -> 1 and e_x(r) -> cos(atan2(x, y))
+        coords = self._coord_sys.symbols
+        d_funcs_deriv = [f.diff(d_var) for f in d_funcs]
+        d_funcs_deriv_sub = []
+        for b in base_scalars:
+            jac = self._coord_sys.jacobian(b._coord_sys, coords)
+            d_funcs_deriv_sub.append(jac[b._index, self._index])
+        d_result = d_result.subs(list(zip(d_funcs_deriv, d_funcs_deriv_sub)))
+
+        # Remove the dummies
+        result = d_result.subs(list(zip(d_funcs, base_scalars)))
+        result = result.subs(list(zip(coords, self._coord_sys.coord_functions())))
+        return result.doit()
+
+
+def _find_coords(expr):
+    # Finds CoordinateSystems existing in expr
+    fields = expr.atoms(BaseScalarField, BaseVectorField)
+    return {f._coord_sys for f in fields}
+
+
+class Commutator(Expr):
+    r"""Commutator of two vector fields.
+
+    Explanation
+    ===========
+
+    The commutator of two vector fields `v_1` and `v_2` is defined as the
+    vector field `[v_1, v_2]` that evaluated on each scalar field `f` is equal
+    to `v_1(v_2(f)) - v_2(v_1(f))`.
+
+    Examples
+    ========
+
+
+    >>> from sympy.diffgeom.rn import R2_p, R2_r
+    >>> from sympy.diffgeom import Commutator
+    >>> from sympy import simplify
+
+    >>> fx, fy = R2_r.base_scalars()
+    >>> e_x, e_y = R2_r.base_vectors()
+    >>> e_r = R2_p.base_vector(0)
+
+    >>> c_xy = Commutator(e_x, e_y)
+    >>> c_xr = Commutator(e_x, e_r)
+    >>> c_xy
+    0
+
+    Unfortunately, the current code is not able to compute everything:
+
+    >>> c_xr
+    Commutator(e_x, e_rho)
+    >>> simplify(c_xr(fy**2))
+    -2*cos(theta)*y**2/(x**2 + y**2)
+
+    """
+    def __new__(cls, v1, v2):
+        if (covariant_order(v1) or contravariant_order(v1) != 1
+                or covariant_order(v2) or contravariant_order(v2) != 1):
+            raise ValueError(
+                'Only commutators of vector fields are supported.')
+        if v1 == v2:
+            return S.Zero
+        coord_sys = set().union(*[_find_coords(v) for v in (v1, v2)])
+        if len(coord_sys) == 1:
+            # Only one coordinate systems is used, hence it is easy enough to
+            # actually evaluate the commutator.
+            if all(isinstance(v, BaseVectorField) for v in (v1, v2)):
+                return S.Zero
+            bases_1, bases_2 = [list(v.atoms(BaseVectorField))
+                                for v in (v1, v2)]
+            coeffs_1 = [v1.expand().coeff(b) for b in bases_1]
+            coeffs_2 = [v2.expand().coeff(b) for b in bases_2]
+            res = 0
+            for c1, b1 in zip(coeffs_1, bases_1):
+                for c2, b2 in zip(coeffs_2, bases_2):
+                    res += c1*b1(c2)*b2 - c2*b2(c1)*b1
+            return res
+        else:
+            obj = super().__new__(cls, v1, v2)
+            obj._v1 = v1 # deprecated assignment
+            obj._v2 = v2 # deprecated assignment
+            return obj
+
+    @property
+    def v1(self):
+        return self.args[0]
+
+    @property
+    def v2(self):
+        return self.args[1]
+
+    def __call__(self, scalar_field):
+        """Apply on a scalar field.
+        If the argument is not a scalar field an error is raised.
+        """
+        return self.v1(self.v2(scalar_field)) - self.v2(self.v1(scalar_field))
+
+
+class Differential(Expr):
+    r"""Return the differential (exterior derivative) of a form field.
+
+    Explanation
+    ===========
+
+    The differential of a form (i.e. the exterior derivative) has a complicated
+    definition in the general case.
+    The differential `df` of the 0-form `f` is defined for any vector field `v`
+    as `df(v) = v(f)`.
+
+    Examples
+    ========
+
+    >>> from sympy import Function
+    >>> from sympy.diffgeom.rn import R2_r
+    >>> from sympy.diffgeom import Differential
+    >>> from sympy import pprint
+
+    >>> fx, fy = R2_r.base_scalars()
+    >>> e_x, e_y = R2_r.base_vectors()
+    >>> g = Function('g')
+    >>> s_field = g(fx, fy)
+    >>> dg = Differential(s_field)
+
+    >>> dg
+    d(g(x, y))
+    >>> pprint(dg(e_x))
+    / d           \|
+    |---(g(xi, y))||
+    \dxi          /|xi=x
+    >>> pprint(dg(e_y))
+    / d           \|
+    |---(g(x, xi))||
+    \dxi          /|xi=y
+
+    Applying the exterior derivative operator twice always results in:
+
+    >>> Differential(dg)
+    0
+    """
+
+    is_commutative = False
+
+    def __new__(cls, form_field):
+        if contravariant_order(form_field):
+            raise ValueError(
+                'A vector field was supplied as an argument to Differential.')
+        if isinstance(form_field, Differential):
+            return S.Zero
+        else:
+            obj = super().__new__(cls, form_field)
+            obj._form_field = form_field # deprecated assignment
+            return obj
+
+    @property
+    def form_field(self):
+        return self.args[0]
+
+    def __call__(self, *vector_fields):
+        """Apply on a list of vector_fields.
+
+        Explanation
+        ===========
+
+        If the number of vector fields supplied is not equal to 1 + the order of
+        the form field inside the differential the result is undefined.
+
+        For 1-forms (i.e. differentials of scalar fields) the evaluation is
+        done as `df(v)=v(f)`. However if `v` is ``None`` instead of a vector
+        field, the differential is returned unchanged. This is done in order to
+        permit partial contractions for higher forms.
+
+        In the general case the evaluation is done by applying the form field
+        inside the differential on a list with one less elements than the number
+        of elements in the original list. Lowering the number of vector fields
+        is achieved through replacing each pair of fields by their
+        commutator.
+
+        If the arguments are not vectors or ``None``s an error is raised.
+        """
+        if any((contravariant_order(a) != 1 or covariant_order(a)) and a is not None
+                for a in vector_fields):
+            raise ValueError('The arguments supplied to Differential should be vector fields or Nones.')
+        k = len(vector_fields)
+        if k == 1:
+            if vector_fields[0]:
+                return vector_fields[0].rcall(self._form_field)
+            return self
+        else:
+            # For higher form it is more complicated:
+            # Invariant formula:
+            # https://en.wikipedia.org/wiki/Exterior_derivative#Invariant_formula
+            # df(v1, ... vn) = +/- vi(f(v1..no i..vn))
+            #                  +/- f([vi,vj],v1..no i, no j..vn)
+            f = self._form_field
+            v = vector_fields
+            ret = 0
+            for i in range(k):
+                t = v[i].rcall(f.rcall(*v[:i] + v[i + 1:]))
+                ret += (-1)**i*t
+                for j in range(i + 1, k):
+                    c = Commutator(v[i], v[j])
+                    if c:  # TODO this is ugly - the Commutator can be Zero and
+                        # this causes the next line to fail
+                        t = f.rcall(*(c,) + v[:i] + v[i + 1:j] + v[j + 1:])
+                        ret += (-1)**(i + j)*t
+            return ret
+
+
+class TensorProduct(Expr):
+    """Tensor product of forms.
+
+    Explanation
+    ===========
+
+    The tensor product permits the creation of multilinear functionals (i.e.
+    higher order tensors) out of lower order fields (e.g. 1-forms and vector
+    fields). However, the higher tensors thus created lack the interesting
+    features provided by the other type of product, the wedge product, namely
+    they are not antisymmetric and hence are not form fields.
+
+    Examples
+    ========
+
+    >>> from sympy.diffgeom.rn import R2_r
+    >>> from sympy.diffgeom import TensorProduct
+
+    >>> fx, fy = R2_r.base_scalars()
+    >>> e_x, e_y = R2_r.base_vectors()
+    >>> dx, dy = R2_r.base_oneforms()
+
+    >>> TensorProduct(dx, dy)(e_x, e_y)
+    1
+    >>> TensorProduct(dx, dy)(e_y, e_x)
+    0
+    >>> TensorProduct(dx, fx*dy)(fx*e_x, e_y)
+    x**2
+    >>> TensorProduct(e_x, e_y)(fx**2, fy**2)
+    4*x*y
+    >>> TensorProduct(e_y, dx)(fy)
+    dx
+
+    You can nest tensor products.
+
+    >>> tp1 = TensorProduct(dx, dy)
+    >>> TensorProduct(tp1, dx)(e_x, e_y, e_x)
+    1
+
+    You can make partial contraction for instance when 'raising an index'.
+    Putting ``None`` in the second argument of ``rcall`` means that the
+    respective position in the tensor product is left as it is.
+
+    >>> TP = TensorProduct
+    >>> metric = TP(dx, dx) + 3*TP(dy, dy)
+    >>> metric.rcall(e_y, None)
+    3*dy
+
+    Or automatically pad the args with ``None`` without specifying them.
+
+    >>> metric.rcall(e_y)
+    3*dy
+
+    """
+    def __new__(cls, *args):
+        scalar = Mul(*[m for m in args if covariant_order(m) + contravariant_order(m) == 0])
+        multifields = [m for m in args if covariant_order(m) + contravariant_order(m)]
+        if multifields:
+            if len(multifields) == 1:
+                return scalar*multifields[0]
+            return scalar*super().__new__(cls, *multifields)
+        else:
+            return scalar
+
+    def __call__(self, *fields):
+        """Apply on a list of fields.
+
+        If the number of input fields supplied is not equal to the order of
+        the tensor product field, the list of arguments is padded with ``None``'s.
+
+        The list of arguments is divided in sublists depending on the order of
+        the forms inside the tensor product. The sublists are provided as
+        arguments to these forms and the resulting expressions are given to the
+        constructor of ``TensorProduct``.
+
+        """
+        tot_order = covariant_order(self) + contravariant_order(self)
+        tot_args = len(fields)
+        if tot_args != tot_order:
+            fields = list(fields) + [None]*(tot_order - tot_args)
+        orders = [covariant_order(f) + contravariant_order(f) for f in self._args]
+        indices = [sum(orders[:i + 1]) for i in range(len(orders) - 1)]
+        fields = [fields[i:j] for i, j in zip([0] + indices, indices + [None])]
+        multipliers = [t[0].rcall(*t[1]) for t in zip(self._args, fields)]
+        return TensorProduct(*multipliers)
+
+
+class WedgeProduct(TensorProduct):
+    """Wedge product of forms.
+
+    Explanation
+    ===========
+
+    In the context of integration only completely antisymmetric forms make
+    sense. The wedge product permits the creation of such forms.
+
+    Examples
+    ========
+
+    >>> from sympy.diffgeom.rn import R2_r
+    >>> from sympy.diffgeom import WedgeProduct
+
+    >>> fx, fy = R2_r.base_scalars()
+    >>> e_x, e_y = R2_r.base_vectors()
+    >>> dx, dy = R2_r.base_oneforms()
+
+    >>> WedgeProduct(dx, dy)(e_x, e_y)
+    1
+    >>> WedgeProduct(dx, dy)(e_y, e_x)
+    -1
+    >>> WedgeProduct(dx, fx*dy)(fx*e_x, e_y)
+    x**2
+    >>> WedgeProduct(e_x, e_y)(fy, None)
+    -e_x
+
+    You can nest wedge products.
+
+    >>> wp1 = WedgeProduct(dx, dy)
+    >>> WedgeProduct(wp1, dx)(e_x, e_y, e_x)
+    0
+
+    """
+    # TODO the calculation of signatures is slow
+    # TODO you do not need all these permutations (neither the prefactor)
+    def __call__(self, *fields):
+        """Apply on a list of vector_fields.
+        The expression is rewritten internally in terms of tensor products and evaluated."""
+        orders = (covariant_order(e) + contravariant_order(e) for e in self.args)
+        mul = 1/Mul(*(factorial(o) for o in orders))
+        perms = permutations(fields)
+        perms_par = (Permutation(
+            p).signature() for p in permutations(range(len(fields))))
+        tensor_prod = TensorProduct(*self.args)
+        return mul*Add(*[tensor_prod(*p[0])*p[1] for p in zip(perms, perms_par)])
+
+
+class LieDerivative(Expr):
+    """Lie derivative with respect to a vector field.
+
+    Explanation
+    ===========
+
+    The transport operator that defines the Lie derivative is the pushforward of
+    the field to be derived along the integral curve of the field with respect
+    to which one derives.
+
+    Examples
+    ========
+
+    >>> from sympy.diffgeom.rn import R2_r, R2_p
+    >>> from sympy.diffgeom import (LieDerivative, TensorProduct)
+
+    >>> fx, fy = R2_r.base_scalars()
+    >>> e_x, e_y = R2_r.base_vectors()
+    >>> e_rho, e_theta = R2_p.base_vectors()
+    >>> dx, dy = R2_r.base_oneforms()
+
+    >>> LieDerivative(e_x, fy)
+    0
+    >>> LieDerivative(e_x, fx)
+    1
+    >>> LieDerivative(e_x, e_x)
+    0
+
+    The Lie derivative of a tensor field by another tensor field is equal to
+    their commutator:
+
+    >>> LieDerivative(e_x, e_rho)
+    Commutator(e_x, e_rho)
+    >>> LieDerivative(e_x + e_y, fx)
+    1
+
+    >>> tp = TensorProduct(dx, dy)
+    >>> LieDerivative(e_x, tp)
+    LieDerivative(e_x, TensorProduct(dx, dy))
+    >>> LieDerivative(e_x, tp)
+    LieDerivative(e_x, TensorProduct(dx, dy))
+
+    """
+    def __new__(cls, v_field, expr):
+        expr_form_ord = covariant_order(expr)
+        if contravariant_order(v_field) != 1 or covariant_order(v_field):
+            raise ValueError('Lie derivatives are defined only with respect to'
+                             ' vector fields. The supplied argument was not a '
+                             'vector field.')
+        if expr_form_ord > 0:
+            obj = super().__new__(cls, v_field, expr)
+            # deprecated assignments
+            obj._v_field = v_field
+            obj._expr = expr
+            return obj
+        if expr.atoms(BaseVectorField):
+            return Commutator(v_field, expr)
+        else:
+            return v_field.rcall(expr)
+
+    @property
+    def v_field(self):
+        return self.args[0]
+
+    @property
+    def expr(self):
+        return self.args[1]
+
+    def __call__(self, *args):
+        v = self.v_field
+        expr = self.expr
+        lead_term = v(expr(*args))
+        rest = Add(*[Mul(*args[:i] + (Commutator(v, args[i]),) + args[i + 1:])
+                     for i in range(len(args))])
+        return lead_term - rest
+
+
+class BaseCovarDerivativeOp(Expr):
+    """Covariant derivative operator with respect to a base vector.
+
+    Examples
+    ========
+
+    >>> from sympy.diffgeom.rn import R2_r
+    >>> from sympy.diffgeom import BaseCovarDerivativeOp
+    >>> from sympy.diffgeom import metric_to_Christoffel_2nd, TensorProduct
+
+    >>> TP = TensorProduct
+    >>> fx, fy = R2_r.base_scalars()
+    >>> e_x, e_y = R2_r.base_vectors()
+    >>> dx, dy = R2_r.base_oneforms()
+
+    >>> ch = metric_to_Christoffel_2nd(TP(dx, dx) + TP(dy, dy))
+    >>> ch
+    [[[0, 0], [0, 0]], [[0, 0], [0, 0]]]
+    >>> cvd = BaseCovarDerivativeOp(R2_r, 0, ch)
+    >>> cvd(fx)
+    1
+    >>> cvd(fx*e_x)
+    e_x
+    """
+
+    def __new__(cls, coord_sys, index, christoffel):
+        index = _sympify(index)
+        christoffel = ImmutableDenseNDimArray(christoffel)
+        obj = super().__new__(cls, coord_sys, index, christoffel)
+        # deprecated assignments
+        obj._coord_sys = coord_sys
+        obj._index = index
+        obj._christoffel = christoffel
+        return obj
+
+    @property
+    def coord_sys(self):
+        return self.args[0]
+
+    @property
+    def index(self):
+        return self.args[1]
+
+    @property
+    def christoffel(self):
+        return self.args[2]
+
+    def __call__(self, field):
+        """Apply on a scalar field.
+
+        The action of a vector field on a scalar field is a directional
+        differentiation.
+        If the argument is not a scalar field the behaviour is undefined.
+        """
+        if covariant_order(field) != 0:
+            raise NotImplementedError()
+
+        field = vectors_in_basis(field, self._coord_sys)
+
+        wrt_vector = self._coord_sys.base_vector(self._index)
+        wrt_scalar = self._coord_sys.coord_function(self._index)
+        vectors = list(field.atoms(BaseVectorField))
+
+        # First step: replace all vectors with something susceptible to
+        # derivation and do the derivation
+        # TODO: you need a real dummy function for the next line
+        d_funcs = [Function('_#_%s' % i)(wrt_scalar) for i,
+                   b in enumerate(vectors)]
+        d_result = field.subs(list(zip(vectors, d_funcs)))
+        d_result = wrt_vector(d_result)
+
+        # Second step: backsubstitute the vectors in
+        d_result = d_result.subs(list(zip(d_funcs, vectors)))
+
+        # Third step: evaluate the derivatives of the vectors
+        derivs = []
+        for v in vectors:
+            d = Add(*[(self._christoffel[k, wrt_vector._index, v._index]
+                       *v._coord_sys.base_vector(k))
+                      for k in range(v._coord_sys.dim)])
+            derivs.append(d)
+        to_subs = [wrt_vector(d) for d in d_funcs]
+        # XXX: This substitution can fail when there are Dummy symbols and the
+        # cache is disabled: https://github.com/sympy/sympy/issues/17794
+        result = d_result.subs(list(zip(to_subs, derivs)))
+
+        # Remove the dummies
+        result = result.subs(list(zip(d_funcs, vectors)))
+        return result.doit()
+
+
+class CovarDerivativeOp(Expr):
+    """Covariant derivative operator.
+
+    Examples
+    ========
+
+    >>> from sympy.diffgeom.rn import R2_r
+    >>> from sympy.diffgeom import CovarDerivativeOp
+    >>> from sympy.diffgeom import metric_to_Christoffel_2nd, TensorProduct
+    >>> TP = TensorProduct
+    >>> fx, fy = R2_r.base_scalars()
+    >>> e_x, e_y = R2_r.base_vectors()
+    >>> dx, dy = R2_r.base_oneforms()
+    >>> ch = metric_to_Christoffel_2nd(TP(dx, dx) + TP(dy, dy))
+
+    >>> ch
+    [[[0, 0], [0, 0]], [[0, 0], [0, 0]]]
+    >>> cvd = CovarDerivativeOp(fx*e_x, ch)
+    >>> cvd(fx)
+    x
+    >>> cvd(fx*e_x)
+    x*e_x
+
+    """
+
+    def __new__(cls, wrt, christoffel):
+        if len({v._coord_sys for v in wrt.atoms(BaseVectorField)}) > 1:
+            raise NotImplementedError()
+        if contravariant_order(wrt) != 1 or covariant_order(wrt):
+            raise ValueError('Covariant derivatives are defined only with '
+                             'respect to vector fields. The supplied argument '
+                             'was not a vector field.')
+        christoffel = ImmutableDenseNDimArray(christoffel)
+        obj = super().__new__(cls, wrt, christoffel)
+        # deprecated assignments
+        obj._wrt = wrt
+        obj._christoffel = christoffel
+        return obj
+
+    @property
+    def wrt(self):
+        return self.args[0]
+
+    @property
+    def christoffel(self):
+        return self.args[1]
+
+    def __call__(self, field):
+        vectors = list(self._wrt.atoms(BaseVectorField))
+        base_ops = [BaseCovarDerivativeOp(v._coord_sys, v._index, self._christoffel)
+                    for v in vectors]
+        return self._wrt.subs(list(zip(vectors, base_ops))).rcall(field)
+
+
+###############################################################################
+# Integral curves on vector fields
+###############################################################################
+def intcurve_series(vector_field, param, start_point, n=6, coord_sys=None, coeffs=False):
+    r"""Return the series expansion for an integral curve of the field.
+
+    Explanation
+    ===========
+
+    Integral curve is a function `\gamma` taking a parameter in `R` to a point
+    in the manifold. It verifies the equation:
+
+    `V(f)\big(\gamma(t)\big) = \frac{d}{dt}f\big(\gamma(t)\big)`
+
+    where the given ``vector_field`` is denoted as `V`. This holds for any
+    value `t` for the parameter and any scalar field `f`.
+
+    This equation can also be decomposed of a basis of coordinate functions
+    `V(f_i)\big(\gamma(t)\big) = \frac{d}{dt}f_i\big(\gamma(t)\big) \quad \forall i`
+
+    This function returns a series expansion of `\gamma(t)` in terms of the
+    coordinate system ``coord_sys``. The equations and expansions are necessarily
+    done in coordinate-system-dependent way as there is no other way to
+    represent movement between points on the manifold (i.e. there is no such
+    thing as a difference of points for a general manifold).
+
+    Parameters
+    ==========
+    vector_field
+        the vector field for which an integral curve will be given
+
+    param
+        the argument of the function `\gamma` from R to the curve
+
+    start_point
+        the point which corresponds to `\gamma(0)`
+
+    n
+        the order to which to expand
+
+    coord_sys
+        the coordinate system in which to expand
+        coeffs (default False) - if True return a list of elements of the expansion
+
+    Examples
+    ========
+
+    Use the predefined R2 manifold:
+
+    >>> from sympy.abc import t, x, y
+    >>> from sympy.diffgeom.rn import R2_p, R2_r
+    >>> from sympy.diffgeom import intcurve_series
+
+    Specify a starting point and a vector field:
+
+    >>> start_point = R2_r.point([x, y])
+    >>> vector_field = R2_r.e_x
+
+    Calculate the series:
+
+    >>> intcurve_series(vector_field, t, start_point, n=3)
+    Matrix([
+    [t + x],
+    [    y]])
+
+    Or get the elements of the expansion in a list:
+
+    >>> series = intcurve_series(vector_field, t, start_point, n=3, coeffs=True)
+    >>> series[0]
+    Matrix([
+    [x],
+    [y]])
+    >>> series[1]
+    Matrix([
+    [t],
+    [0]])
+    >>> series[2]
+    Matrix([
+    [0],
+    [0]])
+
+    The series in the polar coordinate system:
+
+    >>> series = intcurve_series(vector_field, t, start_point,
+    ...             n=3, coord_sys=R2_p, coeffs=True)
+    >>> series[0]
+    Matrix([
+    [sqrt(x**2 + y**2)],
+    [      atan2(y, x)]])
+    >>> series[1]
+    Matrix([
+    [t*x/sqrt(x**2 + y**2)],
+    [   -t*y/(x**2 + y**2)]])
+    >>> series[2]
+    Matrix([
+    [t**2*(-x**2/(x**2 + y**2)**(3/2) + 1/sqrt(x**2 + y**2))/2],
+    [                                t**2*x*y/(x**2 + y**2)**2]])
+
+    See Also
+    ========
+
+    intcurve_diffequ
+
+    """
+    if contravariant_order(vector_field) != 1 or covariant_order(vector_field):
+        raise ValueError('The supplied field was not a vector field.')
+
+    def iter_vfield(scalar_field, i):
+        """Return ``vector_field`` called `i` times on ``scalar_field``."""
+        return reduce(lambda s, v: v.rcall(s), [vector_field, ]*i, scalar_field)
+
+    def taylor_terms_per_coord(coord_function):
+        """Return the series for one of the coordinates."""
+        return [param**i*iter_vfield(coord_function, i).rcall(start_point)/factorial(i)
+                for i in range(n)]
+    coord_sys = coord_sys if coord_sys else start_point._coord_sys
+    coord_functions = coord_sys.coord_functions()
+    taylor_terms = [taylor_terms_per_coord(f) for f in coord_functions]
+    if coeffs:
+        return [Matrix(t) for t in zip(*taylor_terms)]
+    else:
+        return Matrix([sum(c) for c in taylor_terms])
+
+
+def intcurve_diffequ(vector_field, param, start_point, coord_sys=None):
+    r"""Return the differential equation for an integral curve of the field.
+
+    Explanation
+    ===========
+
+    Integral curve is a function `\gamma` taking a parameter in `R` to a point
+    in the manifold. It verifies the equation:
+
+    `V(f)\big(\gamma(t)\big) = \frac{d}{dt}f\big(\gamma(t)\big)`
+
+    where the given ``vector_field`` is denoted as `V`. This holds for any
+    value `t` for the parameter and any scalar field `f`.
+
+    This function returns the differential equation of `\gamma(t)` in terms of the
+    coordinate system ``coord_sys``. The equations and expansions are necessarily
+    done in coordinate-system-dependent way as there is no other way to
+    represent movement between points on the manifold (i.e. there is no such
+    thing as a difference of points for a general manifold).
+
+    Parameters
+    ==========
+
+    vector_field
+        the vector field for which an integral curve will be given
+
+    param
+        the argument of the function `\gamma` from R to the curve
+
+    start_point
+        the point which corresponds to `\gamma(0)`
+
+    coord_sys
+        the coordinate system in which to give the equations
+
+    Returns
+    =======
+
+    a tuple of (equations, initial conditions)
+
+    Examples
+    ========
+
+    Use the predefined R2 manifold:
+
+    >>> from sympy.abc import t
+    >>> from sympy.diffgeom.rn import R2, R2_p, R2_r
+    >>> from sympy.diffgeom import intcurve_diffequ
+
+    Specify a starting point and a vector field:
+
+    >>> start_point = R2_r.point([0, 1])
+    >>> vector_field = -R2.y*R2.e_x + R2.x*R2.e_y
+
+    Get the equation:
+
+    >>> equations, init_cond = intcurve_diffequ(vector_field, t, start_point)
+    >>> equations
+    [f_1(t) + Derivative(f_0(t), t), -f_0(t) + Derivative(f_1(t), t)]
+    >>> init_cond
+    [f_0(0), f_1(0) - 1]
+
+    The series in the polar coordinate system:
+
+    >>> equations, init_cond = intcurve_diffequ(vector_field, t, start_point, R2_p)
+    >>> equations
+    [Derivative(f_0(t), t), Derivative(f_1(t), t) - 1]
+    >>> init_cond
+    [f_0(0) - 1, f_1(0) - pi/2]
+
+    See Also
+    ========
+
+    intcurve_series
+
+    """
+    if contravariant_order(vector_field) != 1 or covariant_order(vector_field):
+        raise ValueError('The supplied field was not a vector field.')
+    coord_sys = coord_sys if coord_sys else start_point._coord_sys
+    gammas = [Function('f_%d' % i)(param) for i in range(
+        start_point._coord_sys.dim)]
+    arbitrary_p = Point(coord_sys, gammas)
+    coord_functions = coord_sys.coord_functions()
+    equations = [simplify(diff(cf.rcall(arbitrary_p), param) - vector_field.rcall(cf).rcall(arbitrary_p))
+                 for cf in coord_functions]
+    init_cond = [simplify(cf.rcall(arbitrary_p).subs(param, 0) - cf.rcall(start_point))
+                 for cf in coord_functions]
+    return equations, init_cond
+
+
+###############################################################################
+# Helpers
+###############################################################################
+def dummyfy(args, exprs):
+    # TODO Is this a good idea?
+    d_args = Matrix([s.as_dummy() for s in args])
+    reps = dict(zip(args, d_args))
+    d_exprs = Matrix([_sympify(expr).subs(reps) for expr in exprs])
+    return d_args, d_exprs
+
+###############################################################################
+# Helpers
+###############################################################################
+def contravariant_order(expr, _strict=False):
+    """Return the contravariant order of an expression.
+
+    Examples
+    ========
+
+    >>> from sympy.diffgeom import contravariant_order
+    >>> from sympy.diffgeom.rn import R2
+    >>> from sympy.abc import a
+
+    >>> contravariant_order(a)
+    0
+    >>> contravariant_order(a*R2.x + 2)
+    0
+    >>> contravariant_order(a*R2.x*R2.e_y + R2.e_x)
+    1
+
+    """
+    # TODO move some of this to class methods.
+    # TODO rewrite using the .as_blah_blah methods
+    if isinstance(expr, Add):
+        orders = [contravariant_order(e) for e in expr.args]
+        if len(set(orders)) != 1:
+            raise ValueError('Misformed expression containing contravariant fields of varying order.')
+        return orders[0]
+    elif isinstance(expr, Mul):
+        orders = [contravariant_order(e) for e in expr.args]
+        not_zero = [o for o in orders if o != 0]
+        if len(not_zero) > 1:
+            raise ValueError('Misformed expression containing multiplication between vectors.')
+        return 0 if not not_zero else not_zero[0]
+    elif isinstance(expr, Pow):
+        if covariant_order(expr.base) or covariant_order(expr.exp):
+            raise ValueError(
+                'Misformed expression containing a power of a vector.')
+        return 0
+    elif isinstance(expr, BaseVectorField):
+        return 1
+    elif isinstance(expr, TensorProduct):
+        return sum(contravariant_order(a) for a in expr.args)
+    elif not _strict or expr.atoms(BaseScalarField):
+        return 0
+    else:  # If it does not contain anything related to the diffgeom module and it is _strict
+        return -1
+
+
+def covariant_order(expr, _strict=False):
+    """Return the covariant order of an expression.
+
+    Examples
+    ========
+
+    >>> from sympy.diffgeom import covariant_order
+    >>> from sympy.diffgeom.rn import R2
+    >>> from sympy.abc import a
+
+    >>> covariant_order(a)
+    0
+    >>> covariant_order(a*R2.x + 2)
+    0
+    >>> covariant_order(a*R2.x*R2.dy + R2.dx)
+    1
+
+    """
+    # TODO move some of this to class methods.
+    # TODO rewrite using the .as_blah_blah methods
+    if isinstance(expr, Add):
+        orders = [covariant_order(e) for e in expr.args]
+        if len(set(orders)) != 1:
+            raise ValueError('Misformed expression containing form fields of varying order.')
+        return orders[0]
+    elif isinstance(expr, Mul):
+        orders = [covariant_order(e) for e in expr.args]
+        not_zero = [o for o in orders if o != 0]
+        if len(not_zero) > 1:
+            raise ValueError('Misformed expression containing multiplication between forms.')
+        return 0 if not not_zero else not_zero[0]
+    elif isinstance(expr, Pow):
+        if covariant_order(expr.base) or covariant_order(expr.exp):
+            raise ValueError(
+                'Misformed expression containing a power of a form.')
+        return 0
+    elif isinstance(expr, Differential):
+        return covariant_order(*expr.args) + 1
+    elif isinstance(expr, TensorProduct):
+        return sum(covariant_order(a) for a in expr.args)
+    elif not _strict or expr.atoms(BaseScalarField):
+        return 0
+    else:  # If it does not contain anything related to the diffgeom module and it is _strict
+        return -1
+
+
+###############################################################################
+# Coordinate transformation functions
+###############################################################################
+def vectors_in_basis(expr, to_sys):
+    """Transform all base vectors in base vectors of a specified coord basis.
+    While the new base vectors are in the new coordinate system basis, any
+    coefficients are kept in the old system.
+
+    Examples
+    ========
+
+    >>> from sympy.diffgeom import vectors_in_basis
+    >>> from sympy.diffgeom.rn import R2_r, R2_p
+
+    >>> vectors_in_basis(R2_r.e_x, R2_p)
+    -y*e_theta/(x**2 + y**2) + x*e_rho/sqrt(x**2 + y**2)
+    >>> vectors_in_basis(R2_p.e_r, R2_r)
+    sin(theta)*e_y + cos(theta)*e_x
+
+    """
+    vectors = list(expr.atoms(BaseVectorField))
+    new_vectors = []
+    for v in vectors:
+        cs = v._coord_sys
+        jac = cs.jacobian(to_sys, cs.coord_functions())
+        new = (jac.T*Matrix(to_sys.base_vectors()))[v._index]
+        new_vectors.append(new)
+    return expr.subs(list(zip(vectors, new_vectors)))
+
+
+###############################################################################
+# Coordinate-dependent functions
+###############################################################################
+def twoform_to_matrix(expr):
+    """Return the matrix representing the twoform.
+
+    For the twoform `w` return the matrix `M` such that `M[i,j]=w(e_i, e_j)`,
+    where `e_i` is the i-th base vector field for the coordinate system in
+    which the expression of `w` is given.
+
+    Examples
+    ========
+
+    >>> from sympy.diffgeom.rn import R2
+    >>> from sympy.diffgeom import twoform_to_matrix, TensorProduct
+    >>> TP = TensorProduct
+
+    >>> twoform_to_matrix(TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
+    Matrix([
+    [1, 0],
+    [0, 1]])
+    >>> twoform_to_matrix(R2.x*TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
+    Matrix([
+    [x, 0],
+    [0, 1]])
+    >>> twoform_to_matrix(TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy) - TP(R2.dx, R2.dy)/2)
+    Matrix([
+    [   1, 0],
+    [-1/2, 1]])
+
+    """
+    if covariant_order(expr) != 2 or contravariant_order(expr):
+        raise ValueError('The input expression is not a two-form.')
+    coord_sys = _find_coords(expr)
+    if len(coord_sys) != 1:
+        raise ValueError('The input expression concerns more than one '
+                         'coordinate systems, hence there is no unambiguous '
+                         'way to choose a coordinate system for the matrix.')
+    coord_sys = coord_sys.pop()
+    vectors = coord_sys.base_vectors()
+    expr = expr.expand()
+    matrix_content = [[expr.rcall(v1, v2) for v1 in vectors]
+                      for v2 in vectors]
+    return Matrix(matrix_content)
+
+
+def metric_to_Christoffel_1st(expr):
+    """Return the nested list of Christoffel symbols for the given metric.
+    This returns the Christoffel symbol of first kind that represents the
+    Levi-Civita connection for the given metric.
+
+    Examples
+    ========
+
+    >>> from sympy.diffgeom.rn import R2
+    >>> from sympy.diffgeom import metric_to_Christoffel_1st, TensorProduct
+    >>> TP = TensorProduct
+
+    >>> metric_to_Christoffel_1st(TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
+    [[[0, 0], [0, 0]], [[0, 0], [0, 0]]]
+    >>> metric_to_Christoffel_1st(R2.x*TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
+    [[[1/2, 0], [0, 0]], [[0, 0], [0, 0]]]
+
+    """
+    matrix = twoform_to_matrix(expr)
+    if not matrix.is_symmetric():
+        raise ValueError(
+            'The two-form representing the metric is not symmetric.')
+    coord_sys = _find_coords(expr).pop()
+    deriv_matrices = [matrix.applyfunc(d) for d in coord_sys.base_vectors()]
+    indices = list(range(coord_sys.dim))
+    christoffel = [[[(deriv_matrices[k][i, j] + deriv_matrices[j][i, k] - deriv_matrices[i][j, k])/2
+                     for k in indices]
+                    for j in indices]
+                   for i in indices]
+    return ImmutableDenseNDimArray(christoffel)
+
+
+def metric_to_Christoffel_2nd(expr):
+    """Return the nested list of Christoffel symbols for the given metric.
+    This returns the Christoffel symbol of second kind that represents the
+    Levi-Civita connection for the given metric.
+
+    Examples
+    ========
+
+    >>> from sympy.diffgeom.rn import R2
+    >>> from sympy.diffgeom import metric_to_Christoffel_2nd, TensorProduct
+    >>> TP = TensorProduct
+
+    >>> metric_to_Christoffel_2nd(TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
+    [[[0, 0], [0, 0]], [[0, 0], [0, 0]]]
+    >>> metric_to_Christoffel_2nd(R2.x*TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
+    [[[1/(2*x), 0], [0, 0]], [[0, 0], [0, 0]]]
+
+    """
+    ch_1st = metric_to_Christoffel_1st(expr)
+    coord_sys = _find_coords(expr).pop()
+    indices = list(range(coord_sys.dim))
+    # XXX workaround, inverting a matrix does not work if it contains non
+    # symbols
+    #matrix = twoform_to_matrix(expr).inv()
+    matrix = twoform_to_matrix(expr)
+    s_fields = set()
+    for e in matrix:
+        s_fields.update(e.atoms(BaseScalarField))
+    s_fields = list(s_fields)
+    dums = coord_sys.symbols
+    matrix = matrix.subs(list(zip(s_fields, dums))).inv().subs(list(zip(dums, s_fields)))
+    # XXX end of workaround
+    christoffel = [[[Add(*[matrix[i, l]*ch_1st[l, j, k] for l in indices])
+                     for k in indices]
+                    for j in indices]
+                   for i in indices]
+    return ImmutableDenseNDimArray(christoffel)
+
+
+def metric_to_Riemann_components(expr):
+    """Return the components of the Riemann tensor expressed in a given basis.
+
+    Given a metric it calculates the components of the Riemann tensor in the
+    canonical basis of the coordinate system in which the metric expression is
+    given.
+
+    Examples
+    ========
+
+    >>> from sympy import exp
+    >>> from sympy.diffgeom.rn import R2
+    >>> from sympy.diffgeom import metric_to_Riemann_components, TensorProduct
+    >>> TP = TensorProduct
+
+    >>> metric_to_Riemann_components(TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
+    [[[[0, 0], [0, 0]], [[0, 0], [0, 0]]], [[[0, 0], [0, 0]], [[0, 0], [0, 0]]]]
+    >>> non_trivial_metric = exp(2*R2.r)*TP(R2.dr, R2.dr) + \
+        R2.r**2*TP(R2.dtheta, R2.dtheta)
+    >>> non_trivial_metric
+    exp(2*rho)*TensorProduct(drho, drho) + rho**2*TensorProduct(dtheta, dtheta)
+    >>> riemann = metric_to_Riemann_components(non_trivial_metric)
+    >>> riemann[0, :, :, :]
+    [[[0, 0], [0, 0]], [[0, exp(-2*rho)*rho], [-exp(-2*rho)*rho, 0]]]
+    >>> riemann[1, :, :, :]
+    [[[0, -1/rho], [1/rho, 0]], [[0, 0], [0, 0]]]
+
+    """
+    ch_2nd = metric_to_Christoffel_2nd(expr)
+    coord_sys = _find_coords(expr).pop()
+    indices = list(range(coord_sys.dim))
+    deriv_ch = [[[[d(ch_2nd[i, j, k])
+                   for d in coord_sys.base_vectors()]
+                  for k in indices]
+                 for j in indices]
+                for i in indices]
+    riemann_a = [[[[deriv_ch[rho][sig][nu][mu] - deriv_ch[rho][sig][mu][nu]
+                    for nu in indices]
+                   for mu in indices]
+                  for sig in indices]
+                     for rho in indices]
+    riemann_b = [[[[Add(*[ch_2nd[rho, l, mu]*ch_2nd[l, sig, nu] - ch_2nd[rho, l, nu]*ch_2nd[l, sig, mu] for l in indices])
+                    for nu in indices]
+                   for mu in indices]
+                  for sig in indices]
+                 for rho in indices]
+    riemann = [[[[riemann_a[rho][sig][mu][nu] + riemann_b[rho][sig][mu][nu]
+                  for nu in indices]
+                     for mu in indices]
+                for sig in indices]
+               for rho in indices]
+    return ImmutableDenseNDimArray(riemann)
+
+
+def metric_to_Ricci_components(expr):
+
+    """Return the components of the Ricci tensor expressed in a given basis.
+
+    Given a metric it calculates the components of the Ricci tensor in the
+    canonical basis of the coordinate system in which the metric expression is
+    given.
+
+    Examples
+    ========
+
+    >>> from sympy import exp
+    >>> from sympy.diffgeom.rn import R2
+    >>> from sympy.diffgeom import metric_to_Ricci_components, TensorProduct
+    >>> TP = TensorProduct
+
+    >>> metric_to_Ricci_components(TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
+    [[0, 0], [0, 0]]
+    >>> non_trivial_metric = exp(2*R2.r)*TP(R2.dr, R2.dr) + \
+                             R2.r**2*TP(R2.dtheta, R2.dtheta)
+    >>> non_trivial_metric
+    exp(2*rho)*TensorProduct(drho, drho) + rho**2*TensorProduct(dtheta, dtheta)
+    >>> metric_to_Ricci_components(non_trivial_metric)
+    [[1/rho, 0], [0, exp(-2*rho)*rho]]
+
+    """
+    riemann = metric_to_Riemann_components(expr)
+    coord_sys = _find_coords(expr).pop()
+    indices = list(range(coord_sys.dim))
+    ricci = [[Add(*[riemann[k, i, k, j] for k in indices])
+              for j in indices]
+             for i in indices]
+    return ImmutableDenseNDimArray(ricci)
+
+###############################################################################
+# Classes for deprecation
+###############################################################################
+
+class _deprecated_container:
+    # This class gives deprecation warning.
+    # When deprecated features are completely deleted, this should be removed as well.
+    # See https://github.com/sympy/sympy/pull/19368
+    def __init__(self, message, data):
+        super().__init__(data)
+        self.message = message
+
+    def warn(self):
+        sympy_deprecation_warning(
+            self.message,
+            deprecated_since_version="1.7",
+            active_deprecations_target="deprecated-diffgeom-mutable",
+            stacklevel=4
+        )
+
+    def __iter__(self):
+        self.warn()
+        return super().__iter__()
+
+    def __getitem__(self, key):
+        self.warn()
+        return super().__getitem__(key)
+
+    def __contains__(self, key):
+        self.warn()
+        return super().__contains__(key)
+
+
+class _deprecated_list(_deprecated_container, list):
+    pass
+
+
+class _deprecated_dict(_deprecated_container, dict):
+    pass
+
+
+# Import at end to avoid cyclic imports
+from sympy.simplify.simplify import simplify

.venv/lib/python3.13/site-packages/sympy/diffgeom/rn.py

@@ -0,0 +1,143 @@
+"""Predefined R^n manifolds together with common coord. systems.
+
+Coordinate systems are predefined as well as the transformation laws between
+them.
+
+Coordinate functions can be accessed as attributes of the manifold (eg `R2.x`),
+as attributes of the coordinate systems (eg `R2_r.x` and `R2_p.theta`), or by
+using the usual `coord_sys.coord_function(index, name)` interface.
+"""
+
+from typing import Any
+import warnings
+
+from sympy.core.symbol import (Dummy, symbols)
+from sympy.functions.elementary.miscellaneous import sqrt
+from sympy.functions.elementary.trigonometric import (acos, atan2, cos, sin)
+from .diffgeom import Manifold, Patch, CoordSystem
+
+__all__ = [
+    'R2', 'R2_origin', 'relations_2d', 'R2_r', 'R2_p',
+    'R3', 'R3_origin', 'relations_3d', 'R3_r', 'R3_c', 'R3_s'
+]
+
+###############################################################################
+# R2
+###############################################################################
+R2: Any = Manifold('R^2', 2)
+
+R2_origin: Any = Patch('origin', R2)
+
+x, y = symbols('x y', real=True)
+r, theta = symbols('rho theta', nonnegative=True)
+
+relations_2d = {
+    ('rectangular', 'polar'): [(x, y), (sqrt(x**2 + y**2), atan2(y, x))],
+    ('polar', 'rectangular'): [(r, theta), (r*cos(theta), r*sin(theta))],
+}
+
+R2_r: Any = CoordSystem('rectangular', R2_origin, (x, y), relations_2d)
+R2_p: Any = CoordSystem('polar', R2_origin, (r, theta), relations_2d)
+
+# support deprecated feature
+with warnings.catch_warnings():
+    warnings.simplefilter("ignore")
+    x, y, r, theta = symbols('x y r theta', cls=Dummy)
+    R2_r.connect_to(R2_p, [x, y],
+                        [sqrt(x**2 + y**2), atan2(y, x)],
+                    inverse=False, fill_in_gaps=False)
+    R2_p.connect_to(R2_r, [r, theta],
+                        [r*cos(theta), r*sin(theta)],
+                    inverse=False, fill_in_gaps=False)
+
+# Defining the basis coordinate functions and adding shortcuts for them to the
+# manifold and the patch.
+R2.x, R2.y = R2_origin.x, R2_origin.y = R2_r.x, R2_r.y = R2_r.coord_functions()
+R2.r, R2.theta = R2_origin.r, R2_origin.theta = R2_p.r, R2_p.theta = R2_p.coord_functions()
+
+# Defining the basis vector fields and adding shortcuts for them to the
+# manifold and the patch.
+R2.e_x, R2.e_y = R2_origin.e_x, R2_origin.e_y = R2_r.e_x, R2_r.e_y = R2_r.base_vectors()
+R2.e_r, R2.e_theta = R2_origin.e_r, R2_origin.e_theta = R2_p.e_r, R2_p.e_theta = R2_p.base_vectors()
+
+# Defining the basis oneform fields and adding shortcuts for them to the
+# manifold and the patch.
+R2.dx, R2.dy = R2_origin.dx, R2_origin.dy = R2_r.dx, R2_r.dy = R2_r.base_oneforms()
+R2.dr, R2.dtheta = R2_origin.dr, R2_origin.dtheta = R2_p.dr, R2_p.dtheta = R2_p.base_oneforms()
+
+###############################################################################
+# R3
+###############################################################################
+R3: Any = Manifold('R^3', 3)
+
+R3_origin: Any = Patch('origin', R3)
+
+x, y, z = symbols('x y z', real=True)
+rho, psi, r, theta, phi = symbols('rho psi r theta phi', nonnegative=True)
+
+relations_3d = {
+    ('rectangular', 'cylindrical'): [(x, y, z),
+                                     (sqrt(x**2 + y**2), atan2(y, x), z)],
+    ('cylindrical', 'rectangular'): [(rho, psi, z),
+                                     (rho*cos(psi), rho*sin(psi), z)],
+    ('rectangular', 'spherical'): [(x, y, z),
+                                   (sqrt(x**2 + y**2 + z**2),
+                                    acos(z/sqrt(x**2 + y**2 + z**2)),
+                                    atan2(y, x))],
+    ('spherical', 'rectangular'): [(r, theta, phi),
+                                   (r*sin(theta)*cos(phi),
+                                    r*sin(theta)*sin(phi),
+                                    r*cos(theta))],
+    ('cylindrical', 'spherical'): [(rho, psi, z),
+                                   (sqrt(rho**2 + z**2),
+                                    acos(z/sqrt(rho**2 + z**2)),
+                                    psi)],
+    ('spherical', 'cylindrical'): [(r, theta, phi),
+                                   (r*sin(theta), phi, r*cos(theta))],
+}
+
+R3_r: Any = CoordSystem('rectangular', R3_origin, (x, y, z), relations_3d)
+R3_c: Any = CoordSystem('cylindrical', R3_origin, (rho, psi, z), relations_3d)
+R3_s: Any = CoordSystem('spherical', R3_origin, (r, theta, phi), relations_3d)
+
+# support deprecated feature
+with warnings.catch_warnings():
+    warnings.simplefilter("ignore")
+    x, y, z, rho, psi, r, theta, phi = symbols('x y z rho psi r theta phi', cls=Dummy)
+    R3_r.connect_to(R3_c, [x, y, z],
+                        [sqrt(x**2 + y**2), atan2(y, x), z],
+                    inverse=False, fill_in_gaps=False)
+    R3_c.connect_to(R3_r, [rho, psi, z],
+                        [rho*cos(psi), rho*sin(psi), z],
+                    inverse=False, fill_in_gaps=False)
+    ## rectangular <-> spherical
+    R3_r.connect_to(R3_s, [x, y, z],
+                        [sqrt(x**2 + y**2 + z**2), acos(z/
+                                sqrt(x**2 + y**2 + z**2)), atan2(y, x)],
+                    inverse=False, fill_in_gaps=False)
+    R3_s.connect_to(R3_r, [r, theta, phi],
+                        [r*sin(theta)*cos(phi), r*sin(
+                            theta)*sin(phi), r*cos(theta)],
+                    inverse=False, fill_in_gaps=False)
+    ## cylindrical <-> spherical
+    R3_c.connect_to(R3_s, [rho, psi, z],
+                        [sqrt(rho**2 + z**2), acos(z/sqrt(rho**2 + z**2)), psi],
+                    inverse=False, fill_in_gaps=False)
+    R3_s.connect_to(R3_c, [r, theta, phi],
+                        [r*sin(theta), phi, r*cos(theta)],
+                    inverse=False, fill_in_gaps=False)
+
+# Defining the basis coordinate functions.
+R3_r.x, R3_r.y, R3_r.z = R3_r.coord_functions()
+R3_c.rho, R3_c.psi, R3_c.z = R3_c.coord_functions()
+R3_s.r, R3_s.theta, R3_s.phi = R3_s.coord_functions()
+
+# Defining the basis vector fields.
+R3_r.e_x, R3_r.e_y, R3_r.e_z = R3_r.base_vectors()
+R3_c.e_rho, R3_c.e_psi, R3_c.e_z = R3_c.base_vectors()
+R3_s.e_r, R3_s.e_theta, R3_s.e_phi = R3_s.base_vectors()
+
+# Defining the basis oneform fields.
+R3_r.dx, R3_r.dy, R3_r.dz = R3_r.base_oneforms()
+R3_c.drho, R3_c.dpsi, R3_c.dz = R3_c.base_oneforms()
+R3_s.dr, R3_s.dtheta, R3_s.dphi = R3_s.base_oneforms()

.venv/lib/python3.13/site-packages/sympy/diffgeom/tests/test_class_structure.py

@@ -0,0 +1,33 @@
+from sympy.diffgeom import Manifold, Patch, CoordSystem, Point
+from sympy.core.function import Function
+from sympy.core.symbol import symbols
+from sympy.testing.pytest import warns_deprecated_sympy
+
+m = Manifold('m', 2)
+p = Patch('p', m)
+a, b = symbols('a b')
+cs = CoordSystem('cs', p, [a, b])
+x, y = symbols('x y')
+f = Function('f')
+s1, s2 = cs.coord_functions()
+v1, v2 = cs.base_vectors()
+f1, f2 = cs.base_oneforms()
+
+def test_point():
+    point = Point(cs, [x, y])
+    assert point != Point(cs, [2, y])
+    #TODO assert point.subs(x, 2) == Point(cs, [2, y])
+    #TODO assert point.free_symbols == set([x, y])
+
+def test_subs():
+    assert s1.subs(s1, s2) == s2
+    assert v1.subs(v1, v2) == v2
+    assert f1.subs(f1, f2) == f2
+    assert (x*f(s1) + y).subs(s1, s2) == x*f(s2) + y
+    assert (f(s1)*v1).subs(v1, v2) == f(s1)*v2
+    assert (y*f(s1)*f1).subs(f1, f2) == y*f(s1)*f2
+
+def test_deprecated():
+    with warns_deprecated_sympy():
+        cs_wname = CoordSystem('cs', p, ['a', 'b'])
+        assert cs_wname == cs_wname.func(*cs_wname.args)

.venv/lib/python3.13/site-packages/sympy/diffgeom/tests/test_diffgeom.py

@@ -0,0 +1,342 @@
+from sympy.core import Lambda, Symbol, symbols
+from sympy.diffgeom.rn import R2, R2_p, R2_r, R3_r, R3_c, R3_s, R2_origin
+from sympy.diffgeom import (Manifold, Patch, CoordSystem, Commutator, Differential, TensorProduct,
+        WedgeProduct, BaseCovarDerivativeOp, CovarDerivativeOp, LieDerivative,
+        covariant_order, contravariant_order, twoform_to_matrix, metric_to_Christoffel_1st,
+        metric_to_Christoffel_2nd, metric_to_Riemann_components,
+        metric_to_Ricci_components, intcurve_diffequ, intcurve_series)
+from sympy.simplify import trigsimp, simplify
+from sympy.functions import sqrt, atan2, sin
+from sympy.matrices import Matrix
+from sympy.testing.pytest import raises, nocache_fail
+from sympy.testing.pytest import warns_deprecated_sympy
+
+TP = TensorProduct
+
+
+def test_coordsys_transform():
+    # test inverse transforms
+    p, q, r, s = symbols('p q r s')
+    rel = {('first', 'second'): [(p, q), (q, -p)]}
+    R2_pq = CoordSystem('first', R2_origin, [p, q], rel)
+    R2_rs = CoordSystem('second', R2_origin, [r, s], rel)
+    r, s = R2_rs.symbols
+    assert R2_rs.transform(R2_pq) == Matrix([[-s], [r]])
+
+    # inverse transform impossible case
+    a, b = symbols('a b', positive=True)
+    rel = {('first', 'second'): [(a,), (-a,)]}
+    R2_a = CoordSystem('first', R2_origin, [a], rel)
+    R2_b = CoordSystem('second', R2_origin, [b], rel)
+    # This transformation is uninvertible because there is no positive a, b satisfying a = -b
+    with raises(NotImplementedError):
+        R2_b.transform(R2_a)
+
+    # inverse transform ambiguous case
+    c, d = symbols('c d')
+    rel = {('first', 'second'): [(c,), (c**2,)]}
+    R2_c = CoordSystem('first', R2_origin, [c], rel)
+    R2_d = CoordSystem('second', R2_origin, [d], rel)
+    # The transform method should throw if it finds multiple inverses for a coordinate transformation.
+    with raises(ValueError):
+        R2_d.transform(R2_c)
+
+    # test indirect transformation
+    a, b, c, d, e, f = symbols('a, b, c, d, e, f')
+    rel = {('C1', 'C2'): [(a, b), (2*a, 3*b)],
+        ('C2', 'C3'): [(c, d), (3*c, 2*d)]}
+    C1 = CoordSystem('C1', R2_origin, (a, b), rel)
+    C2 = CoordSystem('C2', R2_origin, (c, d), rel)
+    C3 = CoordSystem('C3', R2_origin, (e, f), rel)
+    a, b = C1.symbols
+    c, d = C2.symbols
+    e, f = C3.symbols
+    assert C2.transform(C1) == Matrix([c/2, d/3])
+    assert C1.transform(C3) == Matrix([6*a, 6*b])
+    assert C3.transform(C1) == Matrix([e/6, f/6])
+    assert C3.transform(C2) == Matrix([e/3, f/2])
+
+    a, b, c, d, e, f = symbols('a, b, c, d, e, f')
+    rel = {('C1', 'C2'): [(a, b), (2*a, 3*b + 1)],
+        ('C3', 'C2'): [(e, f), (-e - 2, 2*f)]}
+    C1 = CoordSystem('C1', R2_origin, (a, b), rel)
+    C2 = CoordSystem('C2', R2_origin, (c, d), rel)
+    C3 = CoordSystem('C3', R2_origin, (e, f), rel)
+    a, b = C1.symbols
+    c, d = C2.symbols
+    e, f = C3.symbols
+    assert C2.transform(C1) == Matrix([c/2, (d - 1)/3])
+    assert C1.transform(C3) == Matrix([-2*a - 2, (3*b + 1)/2])
+    assert C3.transform(C1) == Matrix([-e/2 - 1, (2*f - 1)/3])
+    assert C3.transform(C2) == Matrix([-e - 2, 2*f])
+
+    # old signature uses Lambda
+    a, b, c, d, e, f = symbols('a, b, c, d, e, f')
+    rel = {('C1', 'C2'): Lambda((a, b), (2*a, 3*b + 1)),
+        ('C3', 'C2'): Lambda((e, f), (-e - 2, 2*f))}
+    C1 = CoordSystem('C1', R2_origin, (a, b), rel)
+    C2 = CoordSystem('C2', R2_origin, (c, d), rel)
+    C3 = CoordSystem('C3', R2_origin, (e, f), rel)
+    a, b = C1.symbols
+    c, d = C2.symbols
+    e, f = C3.symbols
+    assert C2.transform(C1) == Matrix([c/2, (d - 1)/3])
+    assert C1.transform(C3) == Matrix([-2*a - 2, (3*b + 1)/2])
+    assert C3.transform(C1) == Matrix([-e/2 - 1, (2*f - 1)/3])
+    assert C3.transform(C2) == Matrix([-e - 2, 2*f])
+
+
+def test_R2():
+    x0, y0, r0, theta0 = symbols('x0, y0, r0, theta0', real=True)
+    point_r = R2_r.point([x0, y0])
+    point_p = R2_p.point([r0, theta0])
+
+    # r**2 = x**2 + y**2
+    assert (R2.r**2 - R2.x**2 - R2.y**2).rcall(point_r) == 0
+    assert trigsimp( (R2.r**2 - R2.x**2 - R2.y**2).rcall(point_p) ) == 0
+    assert trigsimp(R2.e_r(R2.x**2 + R2.y**2).rcall(point_p).doit()) == 2*r0
+
+    # polar->rect->polar == Id
+    a, b = symbols('a b', positive=True)
+    m = Matrix([[a], [b]])
+
+    #TODO assert m == R2_r.transform(R2_p, R2_p.transform(R2_r, [a, b])).applyfunc(simplify)
+    assert m == R2_p.transform(R2_r, R2_r.transform(R2_p, m)).applyfunc(simplify)
+
+    # deprecated method
+    with warns_deprecated_sympy():
+        assert m == R2_p.coord_tuple_transform_to(
+            R2_r, R2_r.coord_tuple_transform_to(R2_p, m)).applyfunc(simplify)
+
+
+def test_R3():
+    a, b, c = symbols('a b c', positive=True)
+    m = Matrix([[a], [b], [c]])
+
+    assert m == R3_c.transform(R3_r, R3_r.transform(R3_c, m)).applyfunc(simplify)
+    #TODO assert m == R3_r.transform(R3_c, R3_c.transform(R3_r, m)).applyfunc(simplify)
+    assert m == R3_s.transform(
+        R3_r, R3_r.transform(R3_s, m)).applyfunc(simplify)
+    #TODO assert m == R3_r.transform(R3_s, R3_s.transform(R3_r, m)).applyfunc(simplify)
+    assert m == R3_s.transform(
+        R3_c, R3_c.transform(R3_s, m)).applyfunc(simplify)
+    #TODO assert m == R3_c.transform(R3_s, R3_s.transform(R3_c, m)).applyfunc(simplify)
+
+    with warns_deprecated_sympy():
+        assert m == R3_c.coord_tuple_transform_to(
+            R3_r, R3_r.coord_tuple_transform_to(R3_c, m)).applyfunc(simplify)
+        #TODO assert m == R3_r.coord_tuple_transform_to(R3_c, R3_c.coord_tuple_transform_to(R3_r, m)).applyfunc(simplify)
+        assert m == R3_s.coord_tuple_transform_to(
+            R3_r, R3_r.coord_tuple_transform_to(R3_s, m)).applyfunc(simplify)
+        #TODO assert m == R3_r.coord_tuple_transform_to(R3_s, R3_s.coord_tuple_transform_to(R3_r, m)).applyfunc(simplify)
+        assert m == R3_s.coord_tuple_transform_to(
+            R3_c, R3_c.coord_tuple_transform_to(R3_s, m)).applyfunc(simplify)
+        #TODO assert m == R3_c.coord_tuple_transform_to(R3_s, R3_s.coord_tuple_transform_to(R3_c, m)).applyfunc(simplify)
+
+
+def test_CoordinateSymbol():
+    x, y = R2_r.symbols
+    r, theta = R2_p.symbols
+    assert y.rewrite(R2_p) == r*sin(theta)
+
+
+def test_point():
+    x, y = symbols('x, y')
+    p = R2_r.point([x, y])
+    assert p.free_symbols == {x, y}
+    assert p.coords(R2_r) == p.coords() == Matrix([x, y])
+    assert p.coords(R2_p) == Matrix([sqrt(x**2 + y**2), atan2(y, x)])
+
+
+def test_commutator():
+    assert Commutator(R2.e_x, R2.e_y) == 0
+    assert Commutator(R2.x*R2.e_x, R2.x*R2.e_x) == 0
+    assert Commutator(R2.x*R2.e_x, R2.x*R2.e_y) == R2.x*R2.e_y
+    c = Commutator(R2.e_x, R2.e_r)
+    assert c(R2.x) == R2.y*(R2.x**2 + R2.y**2)**(-1)*sin(R2.theta)
+
+
+def test_differential():
+    xdy = R2.x*R2.dy
+    dxdy = Differential(xdy)
+    assert xdy.rcall(None) == xdy
+    assert dxdy(R2.e_x, R2.e_y) == 1
+    assert dxdy(R2.e_x, R2.x*R2.e_y) == R2.x
+    assert Differential(dxdy) == 0
+
+
+def test_products():
+    assert TensorProduct(
+        R2.dx, R2.dy)(R2.e_x, R2.e_y) == R2.dx(R2.e_x)*R2.dy(R2.e_y) == 1
+    assert TensorProduct(R2.dx, R2.dy)(None, R2.e_y) == R2.dx
+    assert TensorProduct(R2.dx, R2.dy)(R2.e_x, None) == R2.dy
+    assert TensorProduct(R2.dx, R2.dy)(R2.e_x) == R2.dy
+    assert TensorProduct(R2.x, R2.dx) == R2.x*R2.dx
+    assert TensorProduct(
+        R2.e_x, R2.e_y)(R2.x, R2.y) == R2.e_x(R2.x) * R2.e_y(R2.y) == 1
+    assert TensorProduct(R2.e_x, R2.e_y)(None, R2.y) == R2.e_x
+    assert TensorProduct(R2.e_x, R2.e_y)(R2.x, None) == R2.e_y
+    assert TensorProduct(R2.e_x, R2.e_y)(R2.x) == R2.e_y
+    assert TensorProduct(R2.x, R2.e_x) == R2.x * R2.e_x
+    assert TensorProduct(
+        R2.dx, R2.e_y)(R2.e_x, R2.y) == R2.dx(R2.e_x) * R2.e_y(R2.y) == 1
+    assert TensorProduct(R2.dx, R2.e_y)(None, R2.y) == R2.dx
+    assert TensorProduct(R2.dx, R2.e_y)(R2.e_x, None) == R2.e_y
+    assert TensorProduct(R2.dx, R2.e_y)(R2.e_x) == R2.e_y
+    assert TensorProduct(R2.x, R2.e_x) == R2.x * R2.e_x
+    assert TensorProduct(
+        R2.e_x, R2.dy)(R2.x, R2.e_y) == R2.e_x(R2.x) * R2.dy(R2.e_y) == 1
+    assert TensorProduct(R2.e_x, R2.dy)(None, R2.e_y) == R2.e_x
+    assert TensorProduct(R2.e_x, R2.dy)(R2.x, None) == R2.dy
+    assert TensorProduct(R2.e_x, R2.dy)(R2.x) == R2.dy
+    assert TensorProduct(R2.e_y,R2.e_x)(R2.x**2 + R2.y**2,R2.x**2 + R2.y**2) == 4*R2.x*R2.y
+
+    assert WedgeProduct(R2.dx, R2.dy)(R2.e_x, R2.e_y) == 1
+    assert WedgeProduct(R2.e_x, R2.e_y)(R2.x, R2.y) == 1
+
+
+def test_lie_derivative():
+    assert LieDerivative(R2.e_x, R2.y) == R2.e_x(R2.y) == 0
+    assert LieDerivative(R2.e_x, R2.x) == R2.e_x(R2.x) == 1
+    assert LieDerivative(R2.e_x, R2.e_x) == Commutator(R2.e_x, R2.e_x) == 0
+    assert LieDerivative(R2.e_x, R2.e_r) == Commutator(R2.e_x, R2.e_r)
+    assert LieDerivative(R2.e_x + R2.e_y, R2.x) == 1
+    assert LieDerivative(
+        R2.e_x, TensorProduct(R2.dx, R2.dy))(R2.e_x, R2.e_y) == 0
+
+
+@nocache_fail
+def test_covar_deriv():
+    ch = metric_to_Christoffel_2nd(TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
+    cvd = BaseCovarDerivativeOp(R2_r, 0, ch)
+    assert cvd(R2.x) == 1
+    # This line fails if the cache is disabled:
+    assert cvd(R2.x*R2.e_x) == R2.e_x
+    cvd = CovarDerivativeOp(R2.x*R2.e_x, ch)
+    assert cvd(R2.x) == R2.x
+    assert cvd(R2.x*R2.e_x) == R2.x*R2.e_x
+
+
+def test_intcurve_diffequ():
+    t = symbols('t')
+    start_point = R2_r.point([1, 0])
+    vector_field = -R2.y*R2.e_x + R2.x*R2.e_y
+    equations, init_cond = intcurve_diffequ(vector_field, t, start_point)
+    assert str(equations) == '[f_1(t) + Derivative(f_0(t), t), -f_0(t) + Derivative(f_1(t), t)]'
+    assert str(init_cond) == '[f_0(0) - 1, f_1(0)]'
+    equations, init_cond = intcurve_diffequ(vector_field, t, start_point, R2_p)
+    assert str(
+        equations) == '[Derivative(f_0(t), t), Derivative(f_1(t), t) - 1]'
+    assert str(init_cond) == '[f_0(0) - 1, f_1(0)]'
+
+
+def test_helpers_and_coordinate_dependent():
+    one_form = R2.dr + R2.dx
+    two_form = Differential(R2.x*R2.dr + R2.r*R2.dx)
+    three_form = Differential(
+        R2.y*two_form) + Differential(R2.x*Differential(R2.r*R2.dr))
+    metric = TensorProduct(R2.dx, R2.dx) + TensorProduct(R2.dy, R2.dy)
+    metric_ambig = TensorProduct(R2.dx, R2.dx) + TensorProduct(R2.dr, R2.dr)
+    misform_a = TensorProduct(R2.dr, R2.dr) + R2.dr
+    misform_b = R2.dr**4
+    misform_c = R2.dx*R2.dy
+    twoform_not_sym = TensorProduct(R2.dx, R2.dx) + TensorProduct(R2.dx, R2.dy)
+    twoform_not_TP = WedgeProduct(R2.dx, R2.dy)
+
+    one_vector = R2.e_x + R2.e_y
+    two_vector = TensorProduct(R2.e_x, R2.e_y)
+    three_vector = TensorProduct(R2.e_x, R2.e_y, R2.e_x)
+    two_wp = WedgeProduct(R2.e_x,R2.e_y)
+
+    assert covariant_order(one_form) == 1
+    assert covariant_order(two_form) == 2
+    assert covariant_order(three_form) == 3
+    assert covariant_order(two_form + metric) == 2
+    assert covariant_order(two_form + metric_ambig) == 2
+    assert covariant_order(two_form + twoform_not_sym) == 2
+    assert covariant_order(two_form + twoform_not_TP) == 2
+
+    assert contravariant_order(one_vector) == 1
+    assert contravariant_order(two_vector) == 2
+    assert contravariant_order(three_vector) == 3
+    assert contravariant_order(two_vector + two_wp) == 2
+
+    raises(ValueError, lambda: covariant_order(misform_a))
+    raises(ValueError, lambda: covariant_order(misform_b))
+    raises(ValueError, lambda: covariant_order(misform_c))
+
+    assert twoform_to_matrix(metric) == Matrix([[1, 0], [0, 1]])
+    assert twoform_to_matrix(twoform_not_sym) == Matrix([[1, 0], [1, 0]])
+    assert twoform_to_matrix(twoform_not_TP) == Matrix([[0, -1], [1, 0]])
+
+    raises(ValueError, lambda: twoform_to_matrix(one_form))
+    raises(ValueError, lambda: twoform_to_matrix(three_form))
+    raises(ValueError, lambda: twoform_to_matrix(metric_ambig))
+
+    raises(ValueError, lambda: metric_to_Christoffel_1st(twoform_not_sym))
+    raises(ValueError, lambda: metric_to_Christoffel_2nd(twoform_not_sym))
+    raises(ValueError, lambda: metric_to_Riemann_components(twoform_not_sym))
+    raises(ValueError, lambda: metric_to_Ricci_components(twoform_not_sym))
+
+
+def test_correct_arguments():
+    raises(ValueError, lambda: R2.e_x(R2.e_x))
+    raises(ValueError, lambda: R2.e_x(R2.dx))
+
+    raises(ValueError, lambda: Commutator(R2.e_x, R2.x))
+    raises(ValueError, lambda: Commutator(R2.dx, R2.e_x))
+
+    raises(ValueError, lambda: Differential(Differential(R2.e_x)))
+
+    raises(ValueError, lambda: R2.dx(R2.x))
+
+    raises(ValueError, lambda: LieDerivative(R2.dx, R2.dx))
+    raises(ValueError, lambda: LieDerivative(R2.x, R2.dx))
+
+    raises(ValueError, lambda: CovarDerivativeOp(R2.dx, []))
+    raises(ValueError, lambda: CovarDerivativeOp(R2.x, []))
+
+    a = Symbol('a')
+    raises(ValueError, lambda: intcurve_series(R2.dx, a, R2_r.point([1, 2])))
+    raises(ValueError, lambda: intcurve_series(R2.x, a, R2_r.point([1, 2])))
+
+    raises(ValueError, lambda: intcurve_diffequ(R2.dx, a, R2_r.point([1, 2])))
+    raises(ValueError, lambda: intcurve_diffequ(R2.x, a, R2_r.point([1, 2])))
+
+    raises(ValueError, lambda: contravariant_order(R2.e_x + R2.dx))
+    raises(ValueError, lambda: covariant_order(R2.e_x + R2.dx))
+
+    raises(ValueError, lambda: contravariant_order(R2.e_x*R2.e_y))
+    raises(ValueError, lambda: covariant_order(R2.dx*R2.dy))
+
+def test_simplify():
+    x, y = R2_r.coord_functions()
+    dx, dy = R2_r.base_oneforms()
+    ex, ey = R2_r.base_vectors()
+    assert simplify(x) == x
+    assert simplify(x*y) == x*y
+    assert simplify(dx*dy) == dx*dy
+    assert simplify(ex*ey) == ex*ey
+    assert ((1-x)*dx)/(1-x)**2 == dx/(1-x)
+
+
+def test_issue_17917():
+    X = R2.x*R2.e_x - R2.y*R2.e_y
+    Y = (R2.x**2 + R2.y**2)*R2.e_x - R2.x*R2.y*R2.e_y
+    assert LieDerivative(X, Y).expand() == (
+        R2.x**2*R2.e_x - 3*R2.y**2*R2.e_x - R2.x*R2.y*R2.e_y)
+
+def test_deprecations():
+    m = Manifold('M', 2)
+    p = Patch('P', m)
+    with warns_deprecated_sympy():
+        CoordSystem('Car2d', p, names=['x', 'y'])
+
+    with warns_deprecated_sympy():
+        c = CoordSystem('Car2d', p, ['x', 'y'])
+
+    with warns_deprecated_sympy():
+        list(m.patches)
+
+    with warns_deprecated_sympy():
+        list(c.transforms)

.venv/lib/python3.13/site-packages/sympy/diffgeom/tests/test_function_diffgeom_book.py

@@ -0,0 +1,145 @@
+from sympy.diffgeom.rn import R2, R2_p, R2_r, R3_r
+from sympy.diffgeom import intcurve_series, Differential, WedgeProduct
+from sympy.core import symbols, Function, Derivative
+from sympy.simplify import trigsimp, simplify
+from sympy.functions import sqrt, atan2, sin, cos
+from sympy.matrices import Matrix
+
+# Most of the functionality is covered in the
+# test_functional_diffgeom_ch* tests which are based on the
+# example from the paper of Sussman and Wisdom.
+# If they do not cover something, additional tests are added in other test
+# functions.
+
+# From "Functional Differential Geometry" as of 2011
+# by Sussman and Wisdom.
+
+
+def test_functional_diffgeom_ch2():
+    x0, y0, r0, theta0 = symbols('x0, y0, r0, theta0', real=True)
+    x, y = symbols('x, y', real=True)
+    f = Function('f')
+
+    assert (R2_p.point_to_coords(R2_r.point([x0, y0])) ==
+           Matrix([sqrt(x0**2 + y0**2), atan2(y0, x0)]))
+    assert (R2_r.point_to_coords(R2_p.point([r0, theta0])) ==
+           Matrix([r0*cos(theta0), r0*sin(theta0)]))
+
+    assert R2_p.jacobian(R2_r, [r0, theta0]) == Matrix(
+        [[cos(theta0), -r0*sin(theta0)], [sin(theta0), r0*cos(theta0)]])
+
+    field = f(R2.x, R2.y)
+    p1_in_rect = R2_r.point([x0, y0])
+    p1_in_polar = R2_p.point([sqrt(x0**2 + y0**2), atan2(y0, x0)])
+    assert field.rcall(p1_in_rect) == f(x0, y0)
+    assert field.rcall(p1_in_polar) == f(x0, y0)
+
+    p_r = R2_r.point([x0, y0])
+    p_p = R2_p.point([r0, theta0])
+    assert R2.x(p_r) == x0
+    assert R2.x(p_p) == r0*cos(theta0)
+    assert R2.r(p_p) == r0
+    assert R2.r(p_r) == sqrt(x0**2 + y0**2)
+    assert R2.theta(p_r) == atan2(y0, x0)
+
+    h = R2.x*R2.r**2 + R2.y**3
+    assert h.rcall(p_r) == x0*(x0**2 + y0**2) + y0**3
+    assert h.rcall(p_p) == r0**3*sin(theta0)**3 + r0**3*cos(theta0)
+
+
+def test_functional_diffgeom_ch3():
+    x0, y0 = symbols('x0, y0', real=True)
+    x, y, t = symbols('x, y, t', real=True)
+    f = Function('f')
+    b1 = Function('b1')
+    b2 = Function('b2')
+    p_r = R2_r.point([x0, y0])
+
+    s_field = f(R2.x, R2.y)
+    v_field = b1(R2.x)*R2.e_x + b2(R2.y)*R2.e_y
+    assert v_field.rcall(s_field).rcall(p_r).doit() == b1(
+        x0)*Derivative(f(x0, y0), x0) + b2(y0)*Derivative(f(x0, y0), y0)
+
+    assert R2.e_x(R2.r**2).rcall(p_r) == 2*x0
+    v = R2.e_x + 2*R2.e_y
+    s = R2.r**2 + 3*R2.x
+    assert v.rcall(s).rcall(p_r).doit() == 2*x0 + 4*y0 + 3
+
+    circ = -R2.y*R2.e_x + R2.x*R2.e_y
+    series = intcurve_series(circ, t, R2_r.point([1, 0]), coeffs=True)
+    series_x, series_y = zip(*series)
+    assert all(
+        term == cos(t).taylor_term(i, t) for i, term in enumerate(series_x))
+    assert all(
+        term == sin(t).taylor_term(i, t) for i, term in enumerate(series_y))
+
+
+def test_functional_diffgeom_ch4():
+    x0, y0, theta0 = symbols('x0, y0, theta0', real=True)
+    x, y, r, theta = symbols('x, y, r, theta', real=True)
+    r0 = symbols('r0', positive=True)
+    f = Function('f')
+    b1 = Function('b1')
+    b2 = Function('b2')
+    p_r = R2_r.point([x0, y0])
+    p_p = R2_p.point([r0, theta0])
+
+    f_field = b1(R2.x, R2.y)*R2.dx + b2(R2.x, R2.y)*R2.dy
+    assert f_field.rcall(R2.e_x).rcall(p_r) == b1(x0, y0)
+    assert f_field.rcall(R2.e_y).rcall(p_r) == b2(x0, y0)
+
+    s_field_r = f(R2.x, R2.y)
+    df = Differential(s_field_r)
+    assert df(R2.e_x).rcall(p_r).doit() == Derivative(f(x0, y0), x0)
+    assert df(R2.e_y).rcall(p_r).doit() == Derivative(f(x0, y0), y0)
+
+    s_field_p = f(R2.r, R2.theta)
+    df = Differential(s_field_p)
+    assert trigsimp(df(R2.e_x).rcall(p_p).doit()) == (
+        cos(theta0)*Derivative(f(r0, theta0), r0) -
+        sin(theta0)*Derivative(f(r0, theta0), theta0)/r0)
+    assert trigsimp(df(R2.e_y).rcall(p_p).doit()) == (
+        sin(theta0)*Derivative(f(r0, theta0), r0) +
+        cos(theta0)*Derivative(f(r0, theta0), theta0)/r0)
+
+    assert R2.dx(R2.e_x).rcall(p_r) == 1
+    assert R2.dx(R2.e_x) == 1
+    assert R2.dx(R2.e_y).rcall(p_r) == 0
+    assert R2.dx(R2.e_y) == 0
+
+    circ = -R2.y*R2.e_x + R2.x*R2.e_y
+    assert R2.dx(circ).rcall(p_r).doit() == -y0
+    assert R2.dy(circ).rcall(p_r) == x0
+    assert R2.dr(circ).rcall(p_r) == 0
+    assert simplify(R2.dtheta(circ).rcall(p_r)) == 1
+
+    assert (circ - R2.e_theta).rcall(s_field_r).rcall(p_r) == 0
+
+
+def test_functional_diffgeom_ch6():
+    u0, u1, u2, v0, v1, v2, w0, w1, w2 = symbols('u0:3, v0:3, w0:3', real=True)
+
+    u = u0*R2.e_x + u1*R2.e_y
+    v = v0*R2.e_x + v1*R2.e_y
+    wp = WedgeProduct(R2.dx, R2.dy)
+    assert wp(u, v) == u0*v1 - u1*v0
+
+    u = u0*R3_r.e_x + u1*R3_r.e_y + u2*R3_r.e_z
+    v = v0*R3_r.e_x + v1*R3_r.e_y + v2*R3_r.e_z
+    w = w0*R3_r.e_x + w1*R3_r.e_y + w2*R3_r.e_z
+    wp = WedgeProduct(R3_r.dx, R3_r.dy, R3_r.dz)
+    assert wp(
+        u, v, w) == Matrix(3, 3, [u0, u1, u2, v0, v1, v2, w0, w1, w2]).det()
+
+    a, b, c = symbols('a, b, c', cls=Function)
+    a_f = a(R3_r.x, R3_r.y, R3_r.z)
+    b_f = b(R3_r.x, R3_r.y, R3_r.z)
+    c_f = c(R3_r.x, R3_r.y, R3_r.z)
+    theta = a_f*R3_r.dx + b_f*R3_r.dy + c_f*R3_r.dz
+    dtheta = Differential(theta)
+    da = Differential(a_f)
+    db = Differential(b_f)
+    dc = Differential(c_f)
+    expr = dtheta - WedgeProduct(
+        da, R3_r.dx) - WedgeProduct(db, R3_r.dy) - WedgeProduct(dc, R3_r.dz)
+    assert expr.rcall(R3_r.e_x, R3_r.e_y) == 0

.venv/lib/python3.13/site-packages/sympy/diffgeom/tests/test_hyperbolic_space.py

@@ -0,0 +1,91 @@
+r'''
+unit test describing the hyperbolic half-plane with the Poincare metric. This
+is a basic model of hyperbolic geometry on the (positive) half-space
+
+{(x,y) \in R^2 | y > 0}
+
+with the Riemannian metric
+
+ds^2 = (dx^2 + dy^2)/y^2
+
+It has constant negative scalar curvature = -2
+
+https://en.wikipedia.org/wiki/Poincare_half-plane_model
+'''
+from sympy.matrices.dense import diag
+from sympy.diffgeom import (twoform_to_matrix,
+                            metric_to_Christoffel_1st, metric_to_Christoffel_2nd,
+                            metric_to_Riemann_components, metric_to_Ricci_components)
+import sympy.diffgeom.rn
+from sympy.tensor.array import ImmutableDenseNDimArray
+
+
+def test_H2():
+    TP = sympy.diffgeom.TensorProduct
+    R2 = sympy.diffgeom.rn.R2
+    y = R2.y
+    dy = R2.dy
+    dx = R2.dx
+    g = (TP(dx, dx) + TP(dy, dy))*y**(-2)
+    automat = twoform_to_matrix(g)
+    mat = diag(y**(-2), y**(-2))
+    assert mat == automat
+
+    gamma1 = metric_to_Christoffel_1st(g)
+    assert gamma1[0, 0, 0] == 0
+    assert gamma1[0, 0, 1] == -y**(-3)
+    assert gamma1[0, 1, 0] == -y**(-3)
+    assert gamma1[0, 1, 1] == 0
+
+    assert gamma1[1, 1, 1] == -y**(-3)
+    assert gamma1[1, 1, 0] == 0
+    assert gamma1[1, 0, 1] == 0
+    assert gamma1[1, 0, 0] == y**(-3)
+
+    gamma2 = metric_to_Christoffel_2nd(g)
+    assert gamma2[0, 0, 0] == 0
+    assert gamma2[0, 0, 1] == -y**(-1)
+    assert gamma2[0, 1, 0] == -y**(-1)
+    assert gamma2[0, 1, 1] == 0
+
+    assert gamma2[1, 1, 1] == -y**(-1)
+    assert gamma2[1, 1, 0] == 0
+    assert gamma2[1, 0, 1] == 0
+    assert gamma2[1, 0, 0] == y**(-1)
+
+    Rm = metric_to_Riemann_components(g)
+    assert Rm[0, 0, 0, 0] == 0
+    assert Rm[0, 0, 0, 1] == 0
+    assert Rm[0, 0, 1, 0] == 0
+    assert Rm[0, 0, 1, 1] == 0
+
+    assert Rm[0, 1, 0, 0] == 0
+    assert Rm[0, 1, 0, 1] == -y**(-2)
+    assert Rm[0, 1, 1, 0] == y**(-2)
+    assert Rm[0, 1, 1, 1] == 0
+
+    assert Rm[1, 0, 0, 0] == 0
+    assert Rm[1, 0, 0, 1] == y**(-2)
+    assert Rm[1, 0, 1, 0] == -y**(-2)
+    assert Rm[1, 0, 1, 1] == 0
+
+    assert Rm[1, 1, 0, 0] == 0
+    assert Rm[1, 1, 0, 1] == 0
+    assert Rm[1, 1, 1, 0] == 0
+    assert Rm[1, 1, 1, 1] == 0
+
+    Ric = metric_to_Ricci_components(g)
+    assert Ric[0, 0] == -y**(-2)
+    assert Ric[0, 1] == 0
+    assert Ric[1, 0] == 0
+    assert Ric[0, 0] == -y**(-2)
+
+    assert Ric == ImmutableDenseNDimArray([-y**(-2), 0, 0, -y**(-2)], (2, 2))
+
+    ## scalar curvature is -2
+    #TODO - it would be nice to have index contraction built-in
+    R = (Ric[0, 0] + Ric[1, 1])*y**2
+    assert R == -2
+
+    ## Gauss curvature is -1
+    assert R/2 == -1

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

@@ -0,0 +1,20 @@
+"""
+Unified place for determining if external dependencies are installed or not.
+
+You should import all external modules using the import_module() function.
+
+For example
+
+>>> from sympy.external import import_module
+>>> numpy = import_module('numpy')
+
+If the resulting library is not installed, or if the installed version
+is less than a given minimum version, the function will return None.
+Otherwise, it will return the library. See the docstring of
+import_module() for more information.
+
+"""
+
+from sympy.external.importtools import import_module
+
+__all__ = ['import_module']

.venv/lib/python3.13/site-packages/sympy/external/gmpy.py

@@ -0,0 +1,342 @@
+from __future__ import annotations
+import os
+from ctypes import c_long, sizeof
+from functools import reduce
+from typing import Type
+from warnings import warn
+
+from sympy.external import import_module
+
+from .pythonmpq import PythonMPQ
+
+from .ntheory import (
+    bit_scan1 as python_bit_scan1,
+    bit_scan0 as python_bit_scan0,
+    remove as python_remove,
+    factorial as python_factorial,
+    sqrt as python_sqrt,
+    sqrtrem as python_sqrtrem,
+    gcd as python_gcd,
+    lcm as python_lcm,
+    gcdext as python_gcdext,
+    is_square as python_is_square,
+    invert as python_invert,
+    legendre as python_legendre,
+    jacobi as python_jacobi,
+    kronecker as python_kronecker,
+    iroot as python_iroot,
+    is_fermat_prp as python_is_fermat_prp,
+    is_euler_prp as python_is_euler_prp,
+    is_strong_prp as python_is_strong_prp,
+    is_fibonacci_prp as python_is_fibonacci_prp,
+    is_lucas_prp as python_is_lucas_prp,
+    is_selfridge_prp as python_is_selfridge_prp,
+    is_strong_lucas_prp as python_is_strong_lucas_prp,
+    is_strong_selfridge_prp as python_is_strong_selfridge_prp,
+    is_bpsw_prp as python_is_bpsw_prp,
+    is_strong_bpsw_prp as python_is_strong_bpsw_prp,
+)
+
+
+__all__ = [
+    # GROUND_TYPES is either 'gmpy' or 'python' depending on which is used. If
+    # gmpy is installed then it will be used unless the environment variable
+    # SYMPY_GROUND_TYPES is set to something other than 'auto', 'gmpy', or
+    # 'gmpy2'.
+    'GROUND_TYPES',
+
+    # If HAS_GMPY is 0, no supported version of gmpy is available. Otherwise,
+    # HAS_GMPY will be 2 for gmpy2 if GROUND_TYPES is 'gmpy'. It used to be
+    # possible for HAS_GMPY to be 1 for gmpy but gmpy is no longer supported.
+    'HAS_GMPY',
+
+    # SYMPY_INTS is a tuple containing the base types for valid integer types.
+    # This is either (int,) or (int, type(mpz(0))) depending on GROUND_TYPES.
+    'SYMPY_INTS',
+
+    # MPQ is either gmpy.mpq or the Python equivalent from
+    # sympy.external.pythonmpq
+    'MPQ',
+
+    # MPZ is either gmpy.mpz or int.
+    'MPZ',
+
+    'bit_scan1',
+    'bit_scan0',
+    'remove',
+    'factorial',
+    'sqrt',
+    'is_square',
+    'sqrtrem',
+    'gcd',
+    'lcm',
+    'gcdext',
+    'invert',
+    'legendre',
+    'jacobi',
+    'kronecker',
+    'iroot',
+    'is_fermat_prp',
+    'is_euler_prp',
+    'is_strong_prp',
+    'is_fibonacci_prp',
+    'is_lucas_prp',
+    'is_selfridge_prp',
+    'is_strong_lucas_prp',
+    'is_strong_selfridge_prp',
+    'is_bpsw_prp',
+    'is_strong_bpsw_prp',
+]
+
+
+#
+# Tested python-flint version. Future versions might work but we will only use
+# them if explicitly requested by SYMPY_GROUND_TYPES=flint.
+#
+_PYTHON_FLINT_VERSION_NEEDED = ["0.6", "0.7", "0.8", "0.9", "0.10"]
+
+
+def _flint_version_okay(flint_version):
+    major, minor = flint_version.split('.')[:2]
+    flint_ver = f'{major}.{minor}'
+    return flint_ver in _PYTHON_FLINT_VERSION_NEEDED
+
+#
+# We will only use gmpy2 >= 2.0.0
+#
+_GMPY2_MIN_VERSION = '2.0.0'
+
+
+def _get_flint(sympy_ground_types):
+    if sympy_ground_types not in ('auto', 'flint'):
+        return None
+
+    try:
+        import flint
+        # Earlier versions of python-flint may not have __version__.
+        from flint import __version__ as _flint_version
+    except ImportError:
+        if sympy_ground_types == 'flint':
+            warn("SYMPY_GROUND_TYPES was set to flint but python-flint is not "
+                 "installed. Falling back to other ground types.")
+        return None
+
+    if _flint_version_okay(_flint_version):
+        return flint
+    elif sympy_ground_types == 'auto':
+        return None
+    else:
+        warn(f"Using python-flint {_flint_version} because SYMPY_GROUND_TYPES "
+             f"is set to flint but this version of SymPy is only tested "
+             f"with python-flint versions {_PYTHON_FLINT_VERSION_NEEDED}.")
+        return flint
+
+
+def _get_gmpy2(sympy_ground_types):
+    if sympy_ground_types not in ('auto', 'gmpy', 'gmpy2'):
+        return None
+
+    gmpy = import_module('gmpy2', min_module_version=_GMPY2_MIN_VERSION,
+            module_version_attr='version', module_version_attr_call_args=())
+
+    if sympy_ground_types != 'auto' and gmpy is None:
+        warn("gmpy2 library is not installed, switching to 'python' ground types")
+
+    return gmpy
+
+
+#
+# SYMPY_GROUND_TYPES can be flint, gmpy, gmpy2, python or auto (default)
+#
+_SYMPY_GROUND_TYPES = os.environ.get('SYMPY_GROUND_TYPES', 'auto').lower()
+_flint = None
+_gmpy = None
+
+#
+# First handle auto-detection of flint/gmpy2. We will prefer flint if available
+# or otherwise gmpy2 if available and then lastly the python types.
+#
+if _SYMPY_GROUND_TYPES in ('auto', 'flint'):
+    _flint = _get_flint(_SYMPY_GROUND_TYPES)
+    if _flint is not None:
+        _SYMPY_GROUND_TYPES = 'flint'
+    else:
+        _SYMPY_GROUND_TYPES = 'auto'
+
+if _SYMPY_GROUND_TYPES in ('auto', 'gmpy', 'gmpy2'):
+    _gmpy = _get_gmpy2(_SYMPY_GROUND_TYPES)
+    if _gmpy is not None:
+        _SYMPY_GROUND_TYPES = 'gmpy'
+    else:
+        _SYMPY_GROUND_TYPES = 'python'
+
+if _SYMPY_GROUND_TYPES not in ('flint', 'gmpy', 'python'):
+    warn("SYMPY_GROUND_TYPES environment variable unrecognised. "
+         "Should be 'auto', 'flint', 'gmpy', 'gmpy2' or 'python'.")
+    _SYMPY_GROUND_TYPES = 'python'
+
+#
+# At this point _SYMPY_GROUND_TYPES is either flint, gmpy or python. The blocks
+# below define the values exported by this module in each case.
+#
+
+#
+# In gmpy2 and flint, there are functions that take a long (or unsigned long)
+# argument. That is, it is not possible to input a value larger than that.
+#
+LONG_MAX = (1 << (8*sizeof(c_long) - 1)) - 1
+
+#
+# Type checkers are confused by what SYMPY_INTS is. There may be a better type
+# hint for this like Type[Integral] or something.
+#
+SYMPY_INTS: tuple[Type, ...]
+
+if _SYMPY_GROUND_TYPES == 'gmpy':
+
+    assert _gmpy is not None
+
+    flint = None
+    gmpy = _gmpy
+
+    HAS_GMPY = 2
+    GROUND_TYPES = 'gmpy'
+    SYMPY_INTS = (int, type(gmpy.mpz(0)))
+    MPZ = gmpy.mpz
+    MPQ = gmpy.mpq
+
+    bit_scan1 = gmpy.bit_scan1
+    bit_scan0 = gmpy.bit_scan0
+    remove = gmpy.remove
+    factorial = gmpy.fac
+    sqrt = gmpy.isqrt
+    is_square = gmpy.is_square
+    sqrtrem = gmpy.isqrt_rem
+    gcd = gmpy.gcd
+    lcm = gmpy.lcm
+    gcdext = gmpy.gcdext
+    invert = gmpy.invert
+    legendre = gmpy.legendre
+    jacobi = gmpy.jacobi
+    kronecker = gmpy.kronecker
+
+    def iroot(x, n):
+        # In the latest gmpy2, the threshold for n is ULONG_MAX,
+        # but adjust to the older one.
+        if n <= LONG_MAX:
+            return gmpy.iroot(x, n)
+        return python_iroot(x, n)
+
+    is_fermat_prp = gmpy.is_fermat_prp
+    is_euler_prp = gmpy.is_euler_prp
+    is_strong_prp = gmpy.is_strong_prp
+    is_fibonacci_prp = gmpy.is_fibonacci_prp
+    is_lucas_prp = gmpy.is_lucas_prp
+    is_selfridge_prp = gmpy.is_selfridge_prp
+    is_strong_lucas_prp = gmpy.is_strong_lucas_prp
+    is_strong_selfridge_prp = gmpy.is_strong_selfridge_prp
+    is_bpsw_prp = gmpy.is_bpsw_prp
+    is_strong_bpsw_prp = gmpy.is_strong_bpsw_prp
+
+elif _SYMPY_GROUND_TYPES == 'flint':
+
+    assert _flint is not None
+
+    flint = _flint
+    gmpy = None
+
+    HAS_GMPY = 0
+    GROUND_TYPES = 'flint'
+    SYMPY_INTS = (int, flint.fmpz) # type: ignore
+    MPZ = flint.fmpz # type: ignore
+    MPQ = flint.fmpq # type: ignore
+
+    bit_scan1 = python_bit_scan1
+    bit_scan0 = python_bit_scan0
+    remove = python_remove
+    factorial = python_factorial
+
+    def sqrt(x):
+        return flint.fmpz(x).isqrt()
+
+    def is_square(x):
+        if x < 0:
+            return False
+        return flint.fmpz(x).sqrtrem()[1] == 0
+
+    def sqrtrem(x):
+        return flint.fmpz(x).sqrtrem()
+
+    def gcd(*args):
+        return reduce(flint.fmpz.gcd, args, flint.fmpz(0))
+
+    def lcm(*args):
+        return reduce(flint.fmpz.lcm, args, flint.fmpz(1))
+
+    gcdext = python_gcdext
+    invert = python_invert
+    legendre = python_legendre
+
+    def jacobi(x, y):
+        if y <= 0 or not y % 2:
+            raise ValueError("y should be an odd positive integer")
+        return flint.fmpz(x).jacobi(y)
+
+    kronecker = python_kronecker
+
+    def iroot(x, n):
+        if n <= LONG_MAX:
+            y = flint.fmpz(x).root(n)
+            return y, y**n == x
+        return python_iroot(x, n)
+
+    is_fermat_prp = python_is_fermat_prp
+    is_euler_prp = python_is_euler_prp
+    is_strong_prp = python_is_strong_prp
+    is_fibonacci_prp = python_is_fibonacci_prp
+    is_lucas_prp = python_is_lucas_prp
+    is_selfridge_prp = python_is_selfridge_prp
+    is_strong_lucas_prp = python_is_strong_lucas_prp
+    is_strong_selfridge_prp = python_is_strong_selfridge_prp
+    is_bpsw_prp = python_is_bpsw_prp
+    is_strong_bpsw_prp = python_is_strong_bpsw_prp
+
+elif _SYMPY_GROUND_TYPES == 'python':
+
+    flint = None
+    gmpy = None
+
+    HAS_GMPY = 0
+    GROUND_TYPES = 'python'
+    SYMPY_INTS = (int,)
+    MPZ = int
+    MPQ = PythonMPQ
+
+    bit_scan1 = python_bit_scan1
+    bit_scan0 = python_bit_scan0
+    remove = python_remove
+    factorial = python_factorial
+    sqrt = python_sqrt
+    is_square = python_is_square
+    sqrtrem = python_sqrtrem
+    gcd = python_gcd
+    lcm = python_lcm
+    gcdext = python_gcdext
+    invert = python_invert
+    legendre = python_legendre
+    jacobi = python_jacobi
+    kronecker = python_kronecker
+    iroot = python_iroot
+    is_fermat_prp = python_is_fermat_prp
+    is_euler_prp = python_is_euler_prp
+    is_strong_prp = python_is_strong_prp
+    is_fibonacci_prp = python_is_fibonacci_prp
+    is_lucas_prp = python_is_lucas_prp
+    is_selfridge_prp = python_is_selfridge_prp
+    is_strong_lucas_prp = python_is_strong_lucas_prp
+    is_strong_selfridge_prp = python_is_strong_selfridge_prp
+    is_bpsw_prp = python_is_bpsw_prp
+    is_strong_bpsw_prp = python_is_strong_bpsw_prp
+
+else:
+    assert False

.venv/lib/python3.13/site-packages/sympy/external/importtools.py

@@ -0,0 +1,187 @@
+"""Tools to assist importing optional external modules."""
+
+import sys
+import re
+
+# Override these in the module to change the default warning behavior.
+# For example, you might set both to False before running the tests so that
+# warnings are not printed to the console, or set both to True for debugging.
+
+WARN_NOT_INSTALLED = None  # Default is False
+WARN_OLD_VERSION = None  # Default is True
+
+
+def __sympy_debug():
+    # helper function from sympy/__init__.py
+    # We don't just import SYMPY_DEBUG from that file because we don't want to
+    # import all of SymPy just to use this module.
+    import os
+    debug_str = os.getenv('SYMPY_DEBUG', 'False')
+    if debug_str in ('True', 'False'):
+        return eval(debug_str)
+    else:
+        raise RuntimeError("unrecognized value for SYMPY_DEBUG: %s" %
+                           debug_str)
+
+if __sympy_debug():
+    WARN_OLD_VERSION = True
+    WARN_NOT_INSTALLED = True
+
+
+_component_re = re.compile(r'(\d+ | [a-z]+ | \.)', re.VERBOSE)
+
+def version_tuple(vstring):
+    # Parse a version string to a tuple e.g. '1.2' -> (1, 2)
+    # Simplified from distutils.version.LooseVersion which was deprecated in
+    # Python 3.10.
+    components = []
+    for x in _component_re.split(vstring):
+        if x and x != '.':
+            try:
+                x = int(x)
+            except ValueError:
+                pass
+            components.append(x)
+    return tuple(components)
+
+
+def import_module(module, min_module_version=None, min_python_version=None,
+        warn_not_installed=None, warn_old_version=None,
+        module_version_attr='__version__', module_version_attr_call_args=None,
+        import_kwargs={}, catch=()):
+    """
+    Import and return a module if it is installed.
+
+    If the module is not installed, it returns None.
+
+    A minimum version for the module can be given as the keyword argument
+    min_module_version.  This should be comparable against the module version.
+    By default, module.__version__ is used to get the module version.  To
+    override this, set the module_version_attr keyword argument.  If the
+    attribute of the module to get the version should be called (e.g.,
+    module.version()), then set module_version_attr_call_args to the args such
+    that module.module_version_attr(*module_version_attr_call_args) returns the
+    module's version.
+
+    If the module version is less than min_module_version using the Python <
+    comparison, None will be returned, even if the module is installed. You can
+    use this to keep from importing an incompatible older version of a module.
+
+    You can also specify a minimum Python version by using the
+    min_python_version keyword argument.  This should be comparable against
+    sys.version_info.
+
+    If the keyword argument warn_not_installed is set to True, the function will
+    emit a UserWarning when the module is not installed.
+
+    If the keyword argument warn_old_version is set to True, the function will
+    emit a UserWarning when the library is installed, but cannot be imported
+    because of the min_module_version or min_python_version options.
+
+    Note that because of the way warnings are handled, a warning will be
+    emitted for each module only once.  You can change the default warning
+    behavior by overriding the values of WARN_NOT_INSTALLED and WARN_OLD_VERSION
+    in sympy.external.importtools.  By default, WARN_NOT_INSTALLED is False and
+    WARN_OLD_VERSION is True.
+
+    This function uses __import__() to import the module.  To pass additional
+    options to __import__(), use the import_kwargs keyword argument.  For
+    example, to import a submodule A.B, you must pass a nonempty fromlist option
+    to __import__.  See the docstring of __import__().
+
+    This catches ImportError to determine if the module is not installed.  To
+    catch additional errors, pass them as a tuple to the catch keyword
+    argument.
+
+    Examples
+    ========
+
+    >>> from sympy.external import import_module
+
+    >>> numpy = import_module('numpy')
+
+    >>> numpy = import_module('numpy', min_python_version=(2, 7),
+    ... warn_old_version=False)
+
+    >>> numpy = import_module('numpy', min_module_version='1.5',
+    ... warn_old_version=False) # numpy.__version__ is a string
+
+    >>> # gmpy does not have __version__, but it does have gmpy.version()
+
+    >>> gmpy = import_module('gmpy', min_module_version='1.14',
+    ... module_version_attr='version', module_version_attr_call_args=(),
+    ... warn_old_version=False)
+
+    >>> # To import a submodule, you must pass a nonempty fromlist to
+    >>> # __import__().  The values do not matter.
+    >>> p3 = import_module('mpl_toolkits.mplot3d',
+    ... import_kwargs={'fromlist':['something']})
+
+    >>> # matplotlib.pyplot can raise RuntimeError when the display cannot be opened
+    >>> matplotlib = import_module('matplotlib',
+    ... import_kwargs={'fromlist':['pyplot']}, catch=(RuntimeError,))
+
+    """
+    # keyword argument overrides default, and global variable overrides
+    # keyword argument.
+    warn_old_version = (WARN_OLD_VERSION if WARN_OLD_VERSION is not None
+        else warn_old_version or True)
+    warn_not_installed = (WARN_NOT_INSTALLED if WARN_NOT_INSTALLED is not None
+        else warn_not_installed or False)
+
+    import warnings
+
+    # Check Python first so we don't waste time importing a module we can't use
+    if min_python_version:
+        if sys.version_info < min_python_version:
+            if warn_old_version:
+                warnings.warn("Python version is too old to use %s "
+                    "(%s or newer required)" % (
+                        module, '.'.join(map(str, min_python_version))),
+                    UserWarning, stacklevel=2)
+            return
+
+    try:
+        mod = __import__(module, **import_kwargs)
+
+        ## there's something funny about imports with matplotlib and py3k. doing
+        ##    from matplotlib import collections
+        ## gives python's stdlib collections module. explicitly re-importing
+        ## the module fixes this.
+        from_list = import_kwargs.get('fromlist', ())
+        for submod in from_list:
+            if submod == 'collections' and mod.__name__ == 'matplotlib':
+                __import__(module + '.' + submod)
+    except ImportError:
+        if warn_not_installed:
+            warnings.warn("%s module is not installed" % module, UserWarning,
+                    stacklevel=2)
+        return
+    except catch as e:
+        if warn_not_installed:
+            warnings.warn(
+                "%s module could not be used (%s)" % (module, repr(e)),
+                stacklevel=2)
+        return
+
+    if min_module_version:
+        modversion = getattr(mod, module_version_attr)
+        if module_version_attr_call_args is not None:
+            modversion = modversion(*module_version_attr_call_args)
+        if version_tuple(modversion) < version_tuple(min_module_version):
+            if warn_old_version:
+                # Attempt to create a pretty string version of the version
+                if isinstance(min_module_version, str):
+                    verstr = min_module_version
+                elif isinstance(min_module_version, (tuple, list)):
+                    verstr = '.'.join(map(str, min_module_version))
+                else:
+                    # Either don't know what this is.  Hopefully
+                    # it's something that has a nice str version, like an int.
+                    verstr = str(min_module_version)
+                warnings.warn("%s version is too old to use "
+                    "(%s or newer required)" % (module, verstr),
+                    UserWarning, stacklevel=2)
+            return
+
+    return mod

.venv/lib/python3.13/site-packages/sympy/external/ntheory.py

@@ -0,0 +1,618 @@
+# sympy.external.ntheory
+#
+# This module provides pure Python implementations of some number theory
+# functions that are alternately used from gmpy2 if it is installed.
+
+import math
+
+import mpmath.libmp as mlib
+
+
+_small_trailing = [0] * 256
+for j in range(1, 8):
+    _small_trailing[1 << j :: 1 << (j + 1)] = [j] * (1 << (7 - j))
+
+
+def bit_scan1(x, n=0):
+    if not x:
+        return
+    x = abs(x >> n)
+    low_byte = x & 0xFF
+    if low_byte:
+        return _small_trailing[low_byte] + n
+
+    t = 8 + n
+    x >>= 8
+    # 2**m is quick for z up through 2**30
+    z = x.bit_length() - 1
+    if x == 1 << z:
+        return z + t
+
+    if z < 300:
+        # fixed 8-byte reduction
+        while not x & 0xFF:
+            x >>= 8
+            t += 8
+    else:
+        # binary reduction important when there might be a large
+        # number of trailing 0s
+        p = z >> 1
+        while not x & 0xFF:
+            while x & ((1 << p) - 1):
+                p >>= 1
+            x >>= p
+            t += p
+    return t + _small_trailing[x & 0xFF]
+
+
+def bit_scan0(x, n=0):
+    return bit_scan1(x + (1 << n), n)
+
+
+def remove(x, f):
+    if f < 2:
+        raise ValueError("factor must be > 1")
+    if x == 0:
+        return 0, 0
+    if f == 2:
+        b = bit_scan1(x)
+        return x >> b, b
+    m = 0
+    y, rem = divmod(x, f)
+    while not rem:
+        x = y
+        m += 1
+        if m > 5:
+            pow_list = [f**2]
+            while pow_list:
+                _f = pow_list[-1]
+                y, rem = divmod(x, _f)
+                if not rem:
+                    m += 1 << len(pow_list)
+                    x = y
+                    pow_list.append(_f**2)
+                else:
+                    pow_list.pop()
+        y, rem = divmod(x, f)
+    return x, m
+
+
+def factorial(x):
+    """Return x!."""
+    return int(mlib.ifac(int(x)))
+
+
+def sqrt(x):
+    """Integer square root of x."""
+    return int(mlib.isqrt(int(x)))
+
+
+def sqrtrem(x):
+    """Integer square root of x and remainder."""
+    s, r = mlib.sqrtrem(int(x))
+    return (int(s), int(r))
+
+
+gcd = math.gcd
+lcm = math.lcm
+
+
+def _sign(n):
+    if n < 0:
+        return -1, -n
+    return 1, n
+
+
+def gcdext(a, b):
+    if not a or not b:
+        g = abs(a) or abs(b)
+        if not g:
+            return (0, 0, 0)
+        return (g, a // g, b // g)
+
+    x_sign, a = _sign(a)
+    y_sign, b = _sign(b)
+    x, r = 1, 0
+    y, s = 0, 1
+
+    while b:
+        q, c = divmod(a, b)
+        a, b = b, c
+        x, r = r, x - q*r
+        y, s = s, y - q*s
+
+    return (a, x * x_sign, y * y_sign)
+
+
+def is_square(x):
+    """Return True if x is a square number."""
+    if x < 0:
+        return False
+
+    # Note that the possible values of y**2 % n for a given n are limited.
+    # For example, when n=4, y**2 % n can only take 0 or 1.
+    # In other words, if x % 4 is 2 or 3, then x is not a square number.
+    # Mathematically, it determines if it belongs to the set {y**2 % n},
+    # but implementationally, it can be realized as a logical conjunction
+    # with an n-bit integer.
+    # see https://mersenneforum.org/showpost.php?p=110896
+    # def magic(n):
+    #     s = {y**2 % n for y in range(n)}
+    #     s = set(range(n)) - s
+    #     return sum(1 << bit for bit in s)
+    # >>> print(hex(magic(128)))
+    # 0xfdfdfdedfdfdfdecfdfdfdedfdfcfdec
+    # >>> print(hex(magic(99)))
+    # 0x5f6f9ffb6fb7ddfcb75befdec
+    # >>> print(hex(magic(91)))
+    # 0x6fd1bfcfed5f3679d3ebdec
+    # >>> print(hex(magic(85)))
+    # 0xdef9ae771ffe3b9d67dec
+    if 0xfdfdfdedfdfdfdecfdfdfdedfdfcfdec & (1 << (x & 127)):
+        return False  # e.g. 2, 3
+    m = x % 765765 # 765765 = 99 * 91 * 85
+    if 0x5f6f9ffb6fb7ddfcb75befdec & (1 << (m % 99)):
+        return False  # e.g. 17, 68
+    if 0x6fd1bfcfed5f3679d3ebdec & (1 << (m % 91)):
+        return False  # e.g. 97, 388
+    if 0xdef9ae771ffe3b9d67dec & (1 << (m % 85)):
+        return False  # e.g. 793, 1408
+    return mlib.sqrtrem(int(x))[1] == 0
+
+
+def invert(x, m):
+    """Modular inverse of x modulo m.
+
+    Returns y such that x*y == 1 mod m.
+
+    Uses ``math.pow`` but reproduces the behaviour of ``gmpy2.invert``
+    which raises ZeroDivisionError if no inverse exists.
+    """
+    try:
+        return pow(x, -1, m)
+    except ValueError:
+        raise ZeroDivisionError("invert() no inverse exists")
+
+
+def legendre(x, y):
+    """Legendre symbol (x / y).
+
+    Following the implementation of gmpy2,
+    the error is raised only when y is an even number.
+    """
+    if y <= 0 or not y % 2:
+        raise ValueError("y should be an odd prime")
+    x %= y
+    if not x:
+        return 0
+    if pow(x, (y - 1) // 2, y) == 1:
+        return 1
+    return -1
+
+
+def jacobi(x, y):
+    """Jacobi symbol (x / y)."""
+    if y <= 0 or not y % 2:
+        raise ValueError("y should be an odd positive integer")
+    x %= y
+    if not x:
+        return int(y == 1)
+    if y == 1 or x == 1:
+        return 1
+    if gcd(x, y) != 1:
+        return 0
+    j = 1
+    while x != 0:
+        while x % 2 == 0 and x > 0:
+            x >>= 1
+            if y % 8 in [3, 5]:
+                j = -j
+        x, y = y, x
+        if x % 4 == y % 4 == 3:
+            j = -j
+        x %= y
+    return j
+
+
+def kronecker(x, y):
+    """Kronecker symbol (x / y)."""
+    if gcd(x, y) != 1:
+        return 0
+    if y == 0:
+        return 1
+    sign = -1 if y < 0 and x < 0 else 1
+    y = abs(y)
+    s = bit_scan1(y)
+    y >>= s
+    if s % 2 and x % 8 in [3, 5]:
+        sign = -sign
+    return sign * jacobi(x, y)
+
+
+def iroot(y, n):
+    if y < 0:
+        raise ValueError("y must be nonnegative")
+    if n < 1:
+        raise ValueError("n must be positive")
+    if y in (0, 1):
+        return y, True
+    if n == 1:
+        return y, True
+    if n == 2:
+        x, rem = mlib.sqrtrem(y)
+        return int(x), not rem
+    if n >= y.bit_length():
+        return 1, False
+    # Get initial estimate for Newton's method. Care must be taken to
+    # avoid overflow
+    try:
+        guess = int(y**(1./n) + 0.5)
+    except OverflowError:
+        exp = math.log2(y)/n
+        if exp > 53:
+            shift = int(exp - 53)
+            guess = int(2.0**(exp - shift) + 1) << shift
+        else:
+            guess = int(2.0**exp)
+    if guess > 2**50:
+        # Newton iteration
+        xprev, x = -1, guess
+        while 1:
+            t = x**(n - 1)
+            xprev, x = x, ((n - 1)*x + y//t)//n
+            if abs(x - xprev) < 2:
+                break
+    else:
+        x = guess
+    # Compensate
+    t = x**n
+    while t < y:
+        x += 1
+        t = x**n
+    while t > y:
+        x -= 1
+        t = x**n
+    return x, t == y
+
+
+def is_fermat_prp(n, a):
+    if a < 2:
+        raise ValueError("is_fermat_prp() requires 'a' greater than or equal to 2")
+    if n < 1:
+        raise ValueError("is_fermat_prp() requires 'n' be greater than 0")
+    if n == 1:
+        return False
+    if n % 2 == 0:
+        return n == 2
+    a %= n
+    if gcd(n, a) != 1:
+        raise ValueError("is_fermat_prp() requires gcd(n,a) == 1")
+    return pow(a, n - 1, n) == 1
+
+
+def is_euler_prp(n, a):
+    if a < 2:
+        raise ValueError("is_euler_prp() requires 'a' greater than or equal to 2")
+    if n < 1:
+        raise ValueError("is_euler_prp() requires 'n' be greater than 0")
+    if n == 1:
+        return False
+    if n % 2 == 0:
+        return n == 2
+    a %= n
+    if gcd(n, a) != 1:
+        raise ValueError("is_euler_prp() requires gcd(n,a) == 1")
+    return pow(a, n >> 1, n) == jacobi(a, n) % n
+
+
+def _is_strong_prp(n, a):
+    s = bit_scan1(n - 1)
+    a = pow(a, n >> s, n)
+    if a == 1 or a == n - 1:
+        return True
+    for _ in range(s - 1):
+        a = pow(a, 2, n)
+        if a == n - 1:
+            return True
+        if a == 1:
+            return False
+    return False
+
+
+def is_strong_prp(n, a):
+    if a < 2:
+        raise ValueError("is_strong_prp() requires 'a' greater than or equal to 2")
+    if n < 1:
+        raise ValueError("is_strong_prp() requires 'n' be greater than 0")
+    if n == 1:
+        return False
+    if n % 2 == 0:
+        return n == 2
+    a %= n
+    if gcd(n, a) != 1:
+        raise ValueError("is_strong_prp() requires gcd(n,a) == 1")
+    return _is_strong_prp(n, a)
+
+
+def _lucas_sequence(n, P, Q, k):
+    r"""Return the modular Lucas sequence (U_k, V_k, Q_k).
+
+    Explanation
+    ===========
+
+    Given a Lucas sequence defined by P, Q, returns the kth values for
+    U and V, along with Q^k, all modulo n. This is intended for use with
+    possibly very large values of n and k, where the combinatorial functions
+    would be completely unusable.
+
+    .. math ::
+        U_k = \begin{cases}
+             0 & \text{if } k = 0\\
+             1 & \text{if } k = 1\\
+             PU_{k-1} - QU_{k-2} & \text{if } k > 1
+        \end{cases}\\
+        V_k = \begin{cases}
+             2 & \text{if } k = 0\\
+             P & \text{if } k = 1\\
+             PV_{k-1} - QV_{k-2} & \text{if } k > 1
+        \end{cases}
+
+    The modular Lucas sequences are used in numerous places in number theory,
+    especially in the Lucas compositeness tests and the various n + 1 proofs.
+
+    Parameters
+    ==========
+
+    n : int
+        n is an odd number greater than or equal to 3
+    P : int
+    Q : int
+        D determined by D = P**2 - 4*Q is non-zero
+    k : int
+        k is a nonnegative integer
+
+    Returns
+    =======
+
+    U, V, Qk : (int, int, int)
+        `(U_k \bmod{n}, V_k \bmod{n}, Q^k \bmod{n})`
+
+    Examples
+    ========
+
+    >>> from sympy.external.ntheory import _lucas_sequence
+    >>> N = 10**2000 + 4561
+    >>> sol = U, V, Qk = _lucas_sequence(N, 3, 1, N//2); sol
+    (0, 2, 1)
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Lucas_sequence
+
+    """
+    if k == 0:
+        return (0, 2, 1)
+    D = P**2 - 4*Q
+    U = 1
+    V = P
+    Qk = Q % n
+    if Q == 1:
+        # Optimization for extra strong tests.
+        for b in bin(k)[3:]:
+            U = (U*V) % n
+            V = (V*V - 2) % n
+            if b == "1":
+                U, V = U*P + V, V*P + U*D
+                if U & 1:
+                    U += n
+                if V & 1:
+                    V += n
+                U, V = U >> 1, V >> 1
+    elif P == 1 and Q == -1:
+        # Small optimization for 50% of Selfridge parameters.
+        for b in bin(k)[3:]:
+            U = (U*V) % n
+            if Qk == 1:
+                V = (V*V - 2) % n
+            else:
+                V = (V*V + 2) % n
+                Qk = 1
+            if b == "1":
+                # new_U = (U + V) // 2
+                # new_V = (5*U + V) // 2 = 2*U + new_U
+                U, V  = U + V, U << 1
+                if U & 1:
+                    U += n
+                U >>= 1
+                V += U
+                Qk = -1
+        Qk %= n
+    elif P == 1:
+        for b in bin(k)[3:]:
+            U = (U*V) % n
+            V = (V*V - 2*Qk) % n
+            Qk *= Qk
+            if b == "1":
+                # new_U = (U + V) // 2
+                # new_V = new_U - 2*Q*U
+                U, V  = U + V, (Q*U) << 1
+                if U & 1:
+                    U += n
+                U >>= 1
+                V = U - V
+                Qk *= Q
+            Qk %= n
+    else:
+        # The general case with any P and Q.
+        for b in bin(k)[3:]:
+            U = (U*V) % n
+            V = (V*V - 2*Qk) % n
+            Qk *= Qk
+            if b == "1":
+                U, V = U*P + V, V*P + U*D
+                if U & 1:
+                    U += n
+                if V & 1:
+                    V += n
+                U, V = U >> 1, V >> 1
+                Qk *= Q
+            Qk %= n
+    return (U % n, V % n, Qk)
+
+
+def is_fibonacci_prp(n, p, q):
+    d = p**2 - 4*q
+    if d == 0 or p <= 0 or q not in [1, -1]:
+        raise ValueError("invalid values for p,q in is_fibonacci_prp()")
+    if n < 1:
+        raise ValueError("is_fibonacci_prp() requires 'n' be greater than 0")
+    if n == 1:
+        return False
+    if n % 2 == 0:
+        return n == 2
+    return _lucas_sequence(n, p, q, n)[1] == p % n
+
+
+def is_lucas_prp(n, p, q):
+    d = p**2 - 4*q
+    if d == 0:
+        raise ValueError("invalid values for p,q in is_lucas_prp()")
+    if n < 1:
+        raise ValueError("is_lucas_prp() requires 'n' be greater than 0")
+    if n == 1:
+        return False
+    if n % 2 == 0:
+        return n == 2
+    if gcd(n, q*d) not in [1, n]:
+        raise ValueError("is_lucas_prp() requires gcd(n,2*q*D) == 1")
+    return _lucas_sequence(n, p, q, n - jacobi(d, n))[0] == 0
+
+
+def _is_selfridge_prp(n):
+    """Lucas compositeness test with the Selfridge parameters for n.
+
+    Explanation
+    ===========
+
+    The Lucas compositeness test checks whether n is a prime number.
+    The test can be run with arbitrary parameters ``P`` and ``Q``, which also change the performance of the test.
+    So, which parameters are most effective for running the Lucas compositeness test?
+    As an algorithm for determining ``P`` and ``Q``, Selfridge proposed method A [1]_ page 1401
+    (Since two methods were proposed, referred to simply as A and B in the paper,
+    we will refer to one of them as "method A").
+
+    method A fixes ``P = 1``. Then, ``D`` defined by ``D = P**2 - 4Q`` is varied from 5, -7, 9, -11, 13, and so on,
+    with the first ``D`` being ``jacobi(D, n) == -1``. Once ``D`` is determined,
+    ``Q`` is determined to be ``(P**2 - D)//4``.
+
+    References
+    ==========
+
+    .. [1] Robert Baillie, Samuel S. Wagstaff, Lucas Pseudoprimes,
+           Math. Comp. Vol 35, Number 152 (1980), pp. 1391-1417,
+           https://doi.org/10.1090%2FS0025-5718-1980-0583518-6
+           http://mpqs.free.fr/LucasPseudoprimes.pdf
+
+    """
+    for D in range(5, 1_000_000, 2):
+        if D & 2: # if D % 4 == 3
+            D = -D
+        j = jacobi(D, n)
+        if j == -1:
+            return _lucas_sequence(n, 1, (1-D) // 4, n + 1)[0] == 0
+        if j == 0 and D % n:
+            return False
+        # When j == -1 is hard to find, suspect a square number
+        if D == 13 and is_square(n):
+            return False
+    raise ValueError("appropriate value for D cannot be found in is_selfridge_prp()")
+
+
+def is_selfridge_prp(n):
+    if n < 1:
+        raise ValueError("is_selfridge_prp() requires 'n' be greater than 0")
+    if n == 1:
+        return False
+    if n % 2 == 0:
+        return n == 2
+    return _is_selfridge_prp(n)
+
+
+def is_strong_lucas_prp(n, p, q):
+    D = p**2 - 4*q
+    if D == 0:
+        raise ValueError("invalid values for p,q in is_strong_lucas_prp()")
+    if n < 1:
+        raise ValueError("is_selfridge_prp() requires 'n' be greater than 0")
+    if n == 1:
+        return False
+    if n % 2 == 0:
+        return n == 2
+    if gcd(n, q*D) not in [1, n]:
+        raise ValueError("is_strong_lucas_prp() requires gcd(n,2*q*D) == 1")
+    j = jacobi(D, n)
+    s = bit_scan1(n - j)
+    U, V, Qk = _lucas_sequence(n, p, q, (n - j) >> s)
+    if U == 0 or V == 0:
+        return True
+    for _ in range(s - 1):
+        V = (V*V - 2*Qk) % n
+        if V == 0:
+            return True
+        Qk = pow(Qk, 2, n)
+    return False
+
+
+def _is_strong_selfridge_prp(n):
+    for D in range(5, 1_000_000, 2):
+        if D & 2: # if D % 4 == 3
+            D = -D
+        j = jacobi(D, n)
+        if j == -1:
+            s = bit_scan1(n + 1)
+            U, V, Qk = _lucas_sequence(n, 1, (1-D) // 4, (n + 1) >> s)
+            if U == 0 or V == 0:
+                return True
+            for _ in range(s - 1):
+                V = (V*V - 2*Qk) % n
+                if V == 0:
+                    return True
+                Qk = pow(Qk, 2, n)
+            return False
+        if j == 0 and D % n:
+            return False
+        # When j == -1 is hard to find, suspect a square number
+        if D == 13 and is_square(n):
+            return False
+    raise ValueError("appropriate value for D cannot be found in is_strong_selfridge_prp()")
+
+
+def is_strong_selfridge_prp(n):
+    if n < 1:
+        raise ValueError("is_strong_selfridge_prp() requires 'n' be greater than 0")
+    if n == 1:
+        return False
+    if n % 2 == 0:
+        return n == 2
+    return _is_strong_selfridge_prp(n)
+
+
+def is_bpsw_prp(n):
+    if n < 1:
+        raise ValueError("is_bpsw_prp() requires 'n' be greater than 0")
+    if n == 1:
+        return False
+    if n % 2 == 0:
+        return n == 2
+    return _is_strong_prp(n, 2) and _is_selfridge_prp(n)
+
+
+def is_strong_bpsw_prp(n):
+    if n < 1:
+        raise ValueError("is_strong_bpsw_prp() requires 'n' be greater than 0")
+    if n == 1:
+        return False
+    if n % 2 == 0:
+        return n == 2
+    return _is_strong_prp(n, 2) and _is_strong_selfridge_prp(n)

.venv/lib/python3.13/site-packages/sympy/external/pythonmpq.py

@@ -0,0 +1,341 @@
+"""
+PythonMPQ: Rational number type based on Python integers.
+
+This class is intended as a pure Python fallback for when gmpy2 is not
+installed. If gmpy2 is installed then its mpq type will be used instead. The
+mpq type is around 20x faster. We could just use the stdlib Fraction class
+here but that is slower:
+
+    from fractions import Fraction
+    from sympy.external.pythonmpq import PythonMPQ
+    nums = range(1000)
+    dens = range(5, 1005)
+    rats = [Fraction(n, d) for n, d in zip(nums, dens)]
+    sum(rats) # <--- 24 milliseconds
+    rats = [PythonMPQ(n, d) for n, d in zip(nums, dens)]
+    sum(rats) # <---  7 milliseconds
+
+Both mpq and Fraction have some awkward features like the behaviour of
+division with // and %:
+
+    >>> from fractions import Fraction
+    >>> Fraction(2, 3) % Fraction(1, 4)
+    1/6
+
+For the QQ domain we do not want this behaviour because there should be no
+remainder when dividing rational numbers. SymPy does not make use of this
+aspect of mpq when gmpy2 is installed. Since this class is a fallback for that
+case we do not bother implementing e.g. __mod__ so that we can be sure we
+are not using it when gmpy2 is installed either.
+"""
+
+from __future__ import annotations
+import operator
+from math import gcd
+from decimal import Decimal
+from fractions import Fraction
+import sys
+from typing import Type
+
+
+# Used for __hash__
+_PyHASH_MODULUS = sys.hash_info.modulus
+_PyHASH_INF = sys.hash_info.inf
+
+
+class PythonMPQ:
+    """Rational number implementation that is intended to be compatible with
+    gmpy2's mpq.
+
+    Also slightly faster than fractions.Fraction.
+
+    PythonMPQ should be treated as immutable although no effort is made to
+    prevent mutation (since that might slow down calculations).
+    """
+    __slots__ = ('numerator', 'denominator')
+
+    def __new__(cls, numerator, denominator=None):
+        """Construct PythonMPQ with gcd computation and checks"""
+        if denominator is not None:
+            #
+            # PythonMPQ(n, d): require n and d to be int and d != 0
+            #
+            if isinstance(numerator, int) and isinstance(denominator, int):
+                # This is the slow part:
+                divisor = gcd(numerator, denominator)
+                numerator //= divisor
+                denominator //= divisor
+                return cls._new_check(numerator, denominator)
+        else:
+            #
+            # PythonMPQ(q)
+            #
+            # Here q can be PythonMPQ, int, Decimal, float, Fraction or str
+            #
+            if isinstance(numerator, int):
+                return cls._new(numerator, 1)
+            elif isinstance(numerator, PythonMPQ):
+                return cls._new(numerator.numerator, numerator.denominator)
+
+            # Let Fraction handle Decimal/float conversion and str parsing
+            if isinstance(numerator, (Decimal, float, str)):
+                numerator = Fraction(numerator)
+            if isinstance(numerator, Fraction):
+                return cls._new(numerator.numerator, numerator.denominator)
+        #
+        # Reject everything else. This is more strict than mpq which allows
+        # things like mpq(Fraction, Fraction) or mpq(Decimal, any). The mpq
+        # behaviour is somewhat inconsistent so we choose to accept only a
+        # more strict subset of what mpq allows.
+        #
+        raise TypeError("PythonMPQ() requires numeric or string argument")
+
+    @classmethod
+    def _new_check(cls, numerator, denominator):
+        """Construct PythonMPQ, check divide by zero and canonicalize signs"""
+        if not denominator:
+            raise ZeroDivisionError(f'Zero divisor {numerator}/{denominator}')
+        elif denominator < 0:
+            numerator = -numerator
+            denominator = -denominator
+        return cls._new(numerator, denominator)
+
+    @classmethod
+    def _new(cls, numerator, denominator):
+        """Construct PythonMPQ efficiently (no checks)"""
+        obj = super().__new__(cls)
+        obj.numerator = numerator
+        obj.denominator = denominator
+        return obj
+
+    def __int__(self):
+        """Convert to int (truncates towards zero)"""
+        p, q = self.numerator, self.denominator
+        if p < 0:
+            return -(-p//q)
+        return p//q
+
+    def __float__(self):
+        """Convert to float (approximately)"""
+        return self.numerator / self.denominator
+
+    def __bool__(self):
+        """True/False if nonzero/zero"""
+        return bool(self.numerator)
+
+    def __eq__(self, other):
+        """Compare equal with PythonMPQ, int, float, Decimal or Fraction"""
+        if isinstance(other, PythonMPQ):
+            return (self.numerator == other.numerator
+                and self.denominator == other.denominator)
+        elif isinstance(other, self._compatible_types):
+            return self.__eq__(PythonMPQ(other))
+        else:
+            return NotImplemented
+
+    def __hash__(self):
+        """hash - same as mpq/Fraction"""
+        try:
+            dinv = pow(self.denominator, -1, _PyHASH_MODULUS)
+        except ValueError:
+            hash_ = _PyHASH_INF
+        else:
+            hash_ = hash(hash(abs(self.numerator)) * dinv)
+        result = hash_ if self.numerator >= 0 else -hash_
+        return -2 if result == -1 else result
+
+    def __reduce__(self):
+        """Deconstruct for pickling"""
+        return type(self), (self.numerator, self.denominator)
+
+    def __str__(self):
+        """Convert to string"""
+        if self.denominator != 1:
+            return f"{self.numerator}/{self.denominator}"
+        else:
+            return f"{self.numerator}"
+
+    def __repr__(self):
+        """Convert to string"""
+        return f"MPQ({self.numerator},{self.denominator})"
+
+    def _cmp(self, other, op):
+        """Helper for lt/le/gt/ge"""
+        if not isinstance(other, self._compatible_types):
+            return NotImplemented
+        lhs = self.numerator * other.denominator
+        rhs = other.numerator * self.denominator
+        return op(lhs, rhs)
+
+    def __lt__(self, other):
+        """self < other"""
+        return self._cmp(other, operator.lt)
+
+    def __le__(self, other):
+        """self <= other"""
+        return self._cmp(other, operator.le)
+
+    def __gt__(self, other):
+        """self > other"""
+        return self._cmp(other, operator.gt)
+
+    def __ge__(self, other):
+        """self >= other"""
+        return self._cmp(other, operator.ge)
+
+    def __abs__(self):
+        """abs(q)"""
+        return self._new(abs(self.numerator), self.denominator)
+
+    def __pos__(self):
+        """+q"""
+        return self
+
+    def __neg__(self):
+        """-q"""
+        return self._new(-self.numerator, self.denominator)
+
+    def __add__(self, other):
+        """q1 + q2"""
+        if isinstance(other, PythonMPQ):
+            #
+            # This is much faster than the naive method used in the stdlib
+            # fractions module. Not sure where this method comes from
+            # though...
+            #
+            # Compare timings for something like:
+            #   nums = range(1000)
+            #   rats = [PythonMPQ(n, d) for n, d in zip(nums[:-5], nums[5:])]
+            #   sum(rats) # <-- time this
+            #
+            ap, aq = self.numerator, self.denominator
+            bp, bq = other.numerator, other.denominator
+            g = gcd(aq, bq)
+            if g == 1:
+                p = ap*bq + aq*bp
+                q = bq*aq
+            else:
+                q1, q2 = aq//g, bq//g
+                p, q = ap*q2 + bp*q1, q1*q2
+                g2 = gcd(p, g)
+                p, q = (p // g2), q * (g // g2)
+
+        elif isinstance(other, int):
+            p = self.numerator + self.denominator * other
+            q = self.denominator
+        else:
+            return NotImplemented
+
+        return self._new(p, q)
+
+    def __radd__(self, other):
+        """z1 + q2"""
+        if isinstance(other, int):
+            p = self.numerator + self.denominator * other
+            q = self.denominator
+            return self._new(p, q)
+        else:
+            return NotImplemented
+
+    def __sub__(self ,other):
+        """q1 - q2"""
+        if isinstance(other, PythonMPQ):
+            ap, aq = self.numerator, self.denominator
+            bp, bq = other.numerator, other.denominator
+            g = gcd(aq, bq)
+            if g == 1:
+                p = ap*bq - aq*bp
+                q = bq*aq
+            else:
+                q1, q2 = aq//g, bq//g
+                p, q = ap*q2 - bp*q1, q1*q2
+                g2 = gcd(p, g)
+                p, q = (p // g2), q * (g // g2)
+        elif isinstance(other, int):
+            p = self.numerator - self.denominator*other
+            q = self.denominator
+        else:
+            return NotImplemented
+
+        return self._new(p, q)
+
+    def __rsub__(self, other):
+        """z1 - q2"""
+        if isinstance(other, int):
+            p = self.denominator * other - self.numerator
+            q = self.denominator
+            return self._new(p, q)
+        else:
+            return NotImplemented
+
+    def __mul__(self, other):
+        """q1 * q2"""
+        if isinstance(other, PythonMPQ):
+            ap, aq = self.numerator, self.denominator
+            bp, bq = other.numerator, other.denominator
+            x1 = gcd(ap, bq)
+            x2 = gcd(bp, aq)
+            p, q = ((ap//x1)*(bp//x2), (aq//x2)*(bq//x1))
+        elif isinstance(other, int):
+            x = gcd(other, self.denominator)
+            p = self.numerator*(other//x)
+            q = self.denominator//x
+        else:
+            return NotImplemented
+
+        return self._new(p, q)
+
+    def __rmul__(self, other):
+        """z1 * q2"""
+        if isinstance(other, int):
+            x = gcd(self.denominator, other)
+            p = self.numerator*(other//x)
+            q = self.denominator//x
+            return self._new(p, q)
+        else:
+            return NotImplemented
+
+    def __pow__(self, exp):
+        """q ** z"""
+        p, q = self.numerator, self.denominator
+
+        if exp < 0:
+            p, q, exp = q, p, -exp
+
+        return self._new_check(p**exp, q**exp)
+
+    def __truediv__(self, other):
+        """q1 / q2"""
+        if isinstance(other, PythonMPQ):
+            ap, aq = self.numerator, self.denominator
+            bp, bq = other.numerator, other.denominator
+            x1 = gcd(ap, bp)
+            x2 = gcd(bq, aq)
+            p, q = ((ap//x1)*(bq//x2), (aq//x2)*(bp//x1))
+        elif isinstance(other, int):
+            x = gcd(other, self.numerator)
+            p = self.numerator//x
+            q = self.denominator*(other//x)
+        else:
+            return NotImplemented
+
+        return self._new_check(p, q)
+
+    def __rtruediv__(self, other):
+        """z / q"""
+        if isinstance(other, int):
+            x = gcd(self.numerator, other)
+            p = self.denominator*(other//x)
+            q = self.numerator//x
+            return self._new_check(p, q)
+        else:
+            return NotImplemented
+
+    _compatible_types: tuple[Type, ...] = ()
+
+#
+# These are the types that PythonMPQ will interoperate with for operations
+# and comparisons such as ==, + etc. We define this down here so that we can
+# include PythonMPQ in the list as well.
+#
+PythonMPQ._compatible_types = (PythonMPQ, int, Decimal, Fraction)

.venv/lib/python3.13/site-packages/sympy/external/tests/test_autowrap.py

@@ -0,0 +1,313 @@
+import sympy
+import tempfile
+import os
+from pathlib import Path
+from sympy.core.mod import Mod
+from sympy.core.relational import Eq
+from sympy.core.symbol import symbols
+from sympy.external import import_module
+from sympy.tensor import IndexedBase, Idx
+from sympy.utilities.autowrap import autowrap, ufuncify, CodeWrapError
+from sympy.testing.pytest import skip
+
+numpy = import_module('numpy', min_module_version='1.6.1')
+Cython = import_module('Cython', min_module_version='0.15.1')
+f2py = import_module('numpy.f2py', import_kwargs={'fromlist': ['f2py']})
+
+f2pyworks = False
+if f2py:
+    try:
+        autowrap(symbols('x'), 'f95', 'f2py')
+    except (CodeWrapError, ImportError, OSError):
+        f2pyworks = False
+    else:
+        f2pyworks = True
+
+a, b, c = symbols('a b c')
+n, m, d = symbols('n m d', integer=True)
+A, B, C = symbols('A B C', cls=IndexedBase)
+i = Idx('i', m)
+j = Idx('j', n)
+k = Idx('k', d)
+
+
+def has_module(module):
+    """
+    Return True if module exists, otherwise run skip().
+
+    module should be a string.
+    """
+    # To give a string of the module name to skip(), this function takes a
+    # string.  So we don't waste time running import_module() more than once,
+    # just map the three modules tested here in this dict.
+    modnames = {'numpy': numpy, 'Cython': Cython, 'f2py': f2py}
+
+    if modnames[module]:
+        if module == 'f2py' and not f2pyworks:
+            skip("Couldn't run f2py.")
+        return True
+    skip("Couldn't import %s." % module)
+
+#
+# test runners used by several language-backend combinations
+#
+
+def runtest_autowrap_twice(language, backend):
+    f = autowrap((((a + b)/c)**5).expand(), language, backend)
+    g = autowrap((((a + b)/c)**4).expand(), language, backend)
+
+    # check that autowrap updates the module name.  Else, g gives the same as f
+    assert f(1, -2, 1) == -1.0
+    assert g(1, -2, 1) == 1.0
+
+
+def runtest_autowrap_trace(language, backend):
+    has_module('numpy')
+    trace = autowrap(A[i, i], language, backend)
+    assert trace(numpy.eye(100)) == 100
+
+
+def runtest_autowrap_matrix_vector(language, backend):
+    has_module('numpy')
+    x, y = symbols('x y', cls=IndexedBase)
+    expr = Eq(y[i], A[i, j]*x[j])
+    mv = autowrap(expr, language, backend)
+
+    # compare with numpy's dot product
+    M = numpy.random.rand(10, 20)
+    x = numpy.random.rand(20)
+    y = numpy.dot(M, x)
+    assert numpy.sum(numpy.abs(y - mv(M, x))) < 1e-13
+
+
+def runtest_autowrap_matrix_matrix(language, backend):
+    has_module('numpy')
+    expr = Eq(C[i, j], A[i, k]*B[k, j])
+    matmat = autowrap(expr, language, backend)
+
+    # compare with numpy's dot product
+    M1 = numpy.random.rand(10, 20)
+    M2 = numpy.random.rand(20, 15)
+    M3 = numpy.dot(M1, M2)
+    assert numpy.sum(numpy.abs(M3 - matmat(M1, M2))) < 1e-13
+
+
+def runtest_ufuncify(language, backend):
+    has_module('numpy')
+    a, b, c = symbols('a b c')
+    fabc = ufuncify([a, b, c], a*b + c, backend=backend)
+    facb = ufuncify([a, c, b], a*b + c, backend=backend)
+    grid = numpy.linspace(-2, 2, 50)
+    b = numpy.linspace(-5, 4, 50)
+    c = numpy.linspace(-1, 1, 50)
+    expected = grid*b + c
+    numpy.testing.assert_allclose(fabc(grid, b, c), expected)
+    numpy.testing.assert_allclose(facb(grid, c, b), expected)
+
+
+def runtest_issue_10274(language, backend):
+    expr = (a - b + c)**(13)
+    tmp = tempfile.mkdtemp()
+    f = autowrap(expr, language, backend, tempdir=tmp,
+                 helpers=('helper', a - b + c, (a, b, c)))
+    assert f(1, 1, 1) == 1
+
+    for file in os.listdir(tmp):
+        if not (file.startswith("wrapped_code_") and file.endswith(".c")):
+            continue
+
+        with open(tmp + '/' + file) as fil:
+            lines = fil.readlines()
+            assert lines[0] == "/******************************************************************************\n"
+            assert "Code generated with SymPy " + sympy.__version__ in lines[1]
+            assert lines[2:] == [
+                " *                                                                            *\n",
+                " *              See http://www.sympy.org/ for more information.               *\n",
+                " *                                                                            *\n",
+                " *                      This file is part of 'autowrap'                       *\n",
+                " ******************************************************************************/\n",
+                "#include " + '"' + file[:-1]+ 'h"' + "\n",
+                "#include <math.h>\n",
+                "\n",
+                "double helper(double a, double b, double c) {\n",
+                "\n",
+                "   double helper_result;\n",
+                "   helper_result = a - b + c;\n",
+                "   return helper_result;\n",
+                "\n",
+                "}\n",
+                "\n",
+                "double autofunc(double a, double b, double c) {\n",
+                "\n",
+                "   double autofunc_result;\n",
+                "   autofunc_result = pow(helper(a, b, c), 13);\n",
+                "   return autofunc_result;\n",
+                "\n",
+                "}\n",
+                ]
+
+
+def runtest_issue_15337(language, backend):
+    has_module('numpy')
+    # NOTE : autowrap was originally designed to only accept an iterable for
+    # the kwarg "helpers", but in issue 10274 the user mistakenly thought that
+    # if there was only a single helper it did not need to be passed via an
+    # iterable that wrapped the helper tuple. There were no tests for this
+    # behavior so when the code was changed to accept a single tuple it broke
+    # the original behavior. These tests below ensure that both now work.
+    a, b, c, d, e = symbols('a, b, c, d, e')
+    expr = (a - b + c - d + e)**13
+    exp_res = (1. - 2. + 3. - 4. + 5.)**13
+
+    f = autowrap(expr, language, backend, args=(a, b, c, d, e),
+                 helpers=('f1', a - b + c, (a, b, c)))
+    numpy.testing.assert_allclose(f(1, 2, 3, 4, 5), exp_res)
+
+    f = autowrap(expr, language, backend, args=(a, b, c, d, e),
+                 helpers=(('f1', a - b, (a, b)), ('f2', c - d, (c, d))))
+    numpy.testing.assert_allclose(f(1, 2, 3, 4, 5), exp_res)
+
+
+def test_issue_15230():
+    has_module('f2py')
+
+    x, y = symbols('x, y')
+    expr = Mod(x, 3.0) - Mod(y, -2.0)
+    f = autowrap(expr, args=[x, y], language='F95')
+    exp_res = float(expr.xreplace({x: 3.5, y: 2.7}).evalf())
+    assert abs(f(3.5, 2.7) - exp_res) < 1e-14
+
+    x, y = symbols('x, y', integer=True)
+    expr = Mod(x, 3) - Mod(y, -2)
+    f = autowrap(expr, args=[x, y], language='F95')
+    assert f(3, 2) == expr.xreplace({x: 3, y: 2})
+
+#
+# tests of language-backend combinations
+#
+
+# f2py
+
+
+def test_wrap_twice_f95_f2py():
+    has_module('f2py')
+    runtest_autowrap_twice('f95', 'f2py')
+
+
+def test_autowrap_trace_f95_f2py():
+    has_module('f2py')
+    runtest_autowrap_trace('f95', 'f2py')
+
+
+def test_autowrap_matrix_vector_f95_f2py():
+    has_module('f2py')
+    runtest_autowrap_matrix_vector('f95', 'f2py')
+
+
+def test_autowrap_matrix_matrix_f95_f2py():
+    has_module('f2py')
+    runtest_autowrap_matrix_matrix('f95', 'f2py')
+
+
+def test_ufuncify_f95_f2py():
+    has_module('f2py')
+    runtest_ufuncify('f95', 'f2py')
+
+
+def test_issue_15337_f95_f2py():
+    has_module('f2py')
+    runtest_issue_15337('f95', 'f2py')
+
+# Cython
+
+
+def test_wrap_twice_c_cython():
+    has_module('Cython')
+    runtest_autowrap_twice('C', 'cython')
+
+
+def test_autowrap_trace_C_Cython():
+    has_module('Cython')
+    runtest_autowrap_trace('C99', 'cython')
+
+
+def test_autowrap_matrix_vector_C_cython():
+    has_module('Cython')
+    runtest_autowrap_matrix_vector('C99', 'cython')
+
+
+def test_autowrap_matrix_matrix_C_cython():
+    has_module('Cython')
+    runtest_autowrap_matrix_matrix('C99', 'cython')
+
+
+def test_ufuncify_C_Cython():
+    has_module('Cython')
+    runtest_ufuncify('C99', 'cython')
+
+
+def test_issue_10274_C_cython():
+    has_module('Cython')
+    runtest_issue_10274('C89', 'cython')
+
+
+def test_issue_15337_C_cython():
+    has_module('Cython')
+    runtest_issue_15337('C89', 'cython')
+
+
+def test_autowrap_custom_printer():
+    has_module('Cython')
+
+    from sympy.core.numbers import pi
+    from sympy.utilities.codegen import C99CodeGen
+    from sympy.printing.c import C99CodePrinter
+
+    class PiPrinter(C99CodePrinter):
+        def _print_Pi(self, expr):
+            return "S_PI"
+
+    printer = PiPrinter()
+    gen = C99CodeGen(printer=printer)
+    gen.preprocessor_statements.append('#include "shortpi.h"')
+
+    expr = pi * a
+
+    expected = (
+        '#include "%s"\n'
+        '#include <math.h>\n'
+        '#include "shortpi.h"\n'
+        '\n'
+        'double autofunc(double a) {\n'
+        '\n'
+        '   double autofunc_result;\n'
+        '   autofunc_result = S_PI*a;\n'
+        '   return autofunc_result;\n'
+        '\n'
+        '}\n'
+    )
+
+    tmpdir = tempfile.mkdtemp()
+    # write a trivial header file to use in the generated code
+    Path(os.path.join(tmpdir, 'shortpi.h')).write_text('#define S_PI 3.14')
+
+    func = autowrap(expr, backend='cython', tempdir=tmpdir, code_gen=gen)
+
+    assert func(4.2) == 3.14 * 4.2
+
+    # check that the generated code is correct
+    for filename in os.listdir(tmpdir):
+        if filename.startswith('wrapped_code') and filename.endswith('.c'):
+            with open(os.path.join(tmpdir, filename)) as f:
+                lines = f.readlines()
+                expected = expected % filename.replace('.c', '.h')
+                assert ''.join(lines[7:]) == expected
+
+
+# Numpy
+
+def test_ufuncify_numpy():
+    # This test doesn't use Cython, but if Cython works, then there is a valid
+    # C compiler, which is needed.
+    has_module('Cython')
+    runtest_ufuncify('C99', 'numpy')

.venv/lib/python3.13/site-packages/sympy/external/tests/test_codegen.py

@@ -0,0 +1,375 @@
+# This tests the compilation and execution of the source code generated with
+# utilities.codegen. The compilation takes place in a temporary directory that
+# is removed after the test. By default the test directory is always removed,
+# but this behavior can be changed by setting the environment variable
+# SYMPY_TEST_CLEAN_TEMP to:
+#   export SYMPY_TEST_CLEAN_TEMP=always   : the default behavior.
+#   export SYMPY_TEST_CLEAN_TEMP=success  : only remove the directories of working tests.
+#   export SYMPY_TEST_CLEAN_TEMP=never    : never remove the directories with the test code.
+# When a directory is not removed, the necessary information is printed on
+# screen to find the files that belong to the (failed) tests. If a test does
+# not fail, py.test captures all the output and you will not see the directories
+# corresponding to the successful tests. Use the --nocapture option to see all
+# the output.
+
+# All tests below have a counterpart in utilities/test/test_codegen.py. In the
+# latter file, the resulting code is compared with predefined strings, without
+# compilation or execution.
+
+# All the generated Fortran code should conform with the Fortran 95 standard,
+# and all the generated C code should be ANSI C, which facilitates the
+# incorporation in various projects. The tests below assume that the binary cc
+# is somewhere in the path and that it can compile ANSI C code.
+
+from sympy.abc import x, y, z
+from sympy.testing.pytest import IS_WASM, skip
+from sympy.utilities.codegen import codegen, make_routine, get_code_generator
+import sys
+import os
+import tempfile
+import subprocess
+from pathlib import Path
+
+
+# templates for the main program that will test the generated code.
+
+main_template = {}
+main_template['F95'] = """
+program main
+  include "codegen.h"
+  integer :: result;
+  result = 0
+
+  %(statements)s
+
+  call exit(result)
+end program
+"""
+
+main_template['C89'] = """
+#include "codegen.h"
+#include <stdio.h>
+#include <math.h>
+
+int main() {
+  int result = 0;
+
+  %(statements)s
+
+  return result;
+}
+"""
+main_template['C99'] = main_template['C89']
+# templates for the numerical tests
+
+numerical_test_template = {}
+numerical_test_template['C89'] = """
+  if (fabs(%(call)s)>%(threshold)s) {
+    printf("Numerical validation failed: %(call)s=%%e threshold=%(threshold)s\\n", %(call)s);
+    result = -1;
+  }
+"""
+numerical_test_template['C99'] = numerical_test_template['C89']
+
+numerical_test_template['F95'] = """
+  if (abs(%(call)s)>%(threshold)s) then
+    write(6,"('Numerical validation failed:')")
+    write(6,"('%(call)s=',e15.5,'threshold=',e15.5)") %(call)s, %(threshold)s
+    result = -1;
+  end if
+"""
+# command sequences for supported compilers
+
+compile_commands = {}
+compile_commands['cc'] = [
+    "cc -c codegen.c -o codegen.o",
+    "cc -c main.c -o main.o",
+    "cc main.o codegen.o -lm -o test.exe"
+]
+
+compile_commands['gfortran'] = [
+    "gfortran -c codegen.f90 -o codegen.o",
+    "gfortran -ffree-line-length-none -c main.f90 -o main.o",
+    "gfortran main.o codegen.o -o test.exe"
+]
+
+compile_commands['g95'] = [
+    "g95 -c codegen.f90 -o codegen.o",
+    "g95 -ffree-line-length-huge -c main.f90 -o main.o",
+    "g95 main.o codegen.o -o test.exe"
+]
+
+compile_commands['ifort'] = [
+    "ifort -c codegen.f90 -o codegen.o",
+    "ifort -c main.f90 -o main.o",
+    "ifort main.o codegen.o -o test.exe"
+]
+
+combinations_lang_compiler = [
+    ('C89', 'cc'),
+    ('C99', 'cc'),
+    ('F95', 'ifort'),
+    ('F95', 'gfortran'),
+    ('F95', 'g95')
+]
+
+def try_run(commands):
+    """Run a series of commands and only return True if all ran fine."""
+    if IS_WASM:
+        return False
+    with open(os.devnull, 'w') as null:
+        for command in commands:
+            retcode = subprocess.call(command, stdout=null, shell=True,
+                    stderr=subprocess.STDOUT)
+            if retcode != 0:
+                return False
+    return True
+
+
+def run_test(label, routines, numerical_tests, language, commands, friendly=True):
+    """A driver for the codegen tests.
+
+       This driver assumes that a compiler ifort is present in the PATH and that
+       ifort is (at least) a Fortran 90 compiler. The generated code is written in
+       a temporary directory, together with a main program that validates the
+       generated code. The test passes when the compilation and the validation
+       run correctly.
+    """
+
+    # Check input arguments before touching the file system
+    language = language.upper()
+    assert language in main_template
+    assert language in numerical_test_template
+
+    # Check that environment variable makes sense
+    clean = os.getenv('SYMPY_TEST_CLEAN_TEMP', 'always').lower()
+    if clean not in ('always', 'success', 'never'):
+        raise ValueError("SYMPY_TEST_CLEAN_TEMP must be one of the following: 'always', 'success' or 'never'.")
+
+    # Do all the magic to compile, run and validate the test code
+    # 1) prepare the temporary working directory, switch to that dir
+    work = tempfile.mkdtemp("_sympy_%s_test" % language, "%s_" % label)
+    oldwork = os.getcwd()
+    os.chdir(work)
+
+    # 2) write the generated code
+    if friendly:
+        # interpret the routines as a name_expr list and call the friendly
+        # function codegen
+        codegen(routines, language, "codegen", to_files=True)
+    else:
+        code_gen = get_code_generator(language, "codegen")
+        code_gen.write(routines, "codegen", to_files=True)
+
+    # 3) write a simple main program that links to the generated code, and that
+    #    includes the numerical tests
+    test_strings = []
+    for fn_name, args, expected, threshold in numerical_tests:
+        call_string = "%s(%s)-(%s)" % (
+            fn_name, ",".join(str(arg) for arg in args), expected)
+        if language == "F95":
+            call_string = fortranize_double_constants(call_string)
+            threshold = fortranize_double_constants(str(threshold))
+        test_strings.append(numerical_test_template[language] % {
+            "call": call_string,
+            "threshold": threshold,
+        })
+
+    if language == "F95":
+        f_name = "main.f90"
+    elif language.startswith("C"):
+        f_name = "main.c"
+    else:
+        raise NotImplementedError(
+            "FIXME: filename extension unknown for language: %s" % language)
+
+    Path(f_name).write_text(
+        main_template[language] % {'statements': "".join(test_strings)})
+
+    # 4) Compile and link
+    compiled = try_run(commands)
+
+    # 5) Run if compiled
+    if compiled:
+        executed = try_run(["./test.exe"])
+    else:
+        executed = False
+
+    # 6) Clean up stuff
+    if clean == 'always' or (clean == 'success' and compiled and executed):
+        def safe_remove(filename):
+            if os.path.isfile(filename):
+                os.remove(filename)
+        safe_remove("codegen.f90")
+        safe_remove("codegen.c")
+        safe_remove("codegen.h")
+        safe_remove("codegen.o")
+        safe_remove("main.f90")
+        safe_remove("main.c")
+        safe_remove("main.o")
+        safe_remove("test.exe")
+        os.chdir(oldwork)
+        os.rmdir(work)
+    else:
+        print("TEST NOT REMOVED: %s" % work, file=sys.stderr)
+        os.chdir(oldwork)
+
+    # 7) Do the assertions in the end
+    assert compiled, "failed to compile %s code with:\n%s" % (
+        language, "\n".join(commands))
+    assert executed, "failed to execute %s code from:\n%s" % (
+        language, "\n".join(commands))
+
+
+def fortranize_double_constants(code_string):
+    """
+    Replaces every literal float with literal doubles
+    """
+    import re
+    pattern_exp = re.compile(r'\d+(\.)?\d*[eE]-?\d+')
+    pattern_float = re.compile(r'\d+\.\d*(?!\d*d)')
+
+    def subs_exp(matchobj):
+        return re.sub('[eE]', 'd', matchobj.group(0))
+
+    def subs_float(matchobj):
+        return "%sd0" % matchobj.group(0)
+
+    code_string = pattern_exp.sub(subs_exp, code_string)
+    code_string = pattern_float.sub(subs_float, code_string)
+
+    return code_string
+
+
+def is_feasible(language, commands):
+    # This test should always work, otherwise the compiler is not present.
+    routine = make_routine("test", x)
+    numerical_tests = [
+        ("test", ( 1.0,), 1.0, 1e-15),
+        ("test", (-1.0,), -1.0, 1e-15),
+    ]
+    try:
+        run_test("is_feasible", [routine], numerical_tests, language, commands,
+                 friendly=False)
+        return True
+    except AssertionError:
+        return False
+
+valid_lang_commands = []
+invalid_lang_compilers = []
+for lang, compiler in combinations_lang_compiler:
+    commands = compile_commands[compiler]
+    if is_feasible(lang, commands):
+        valid_lang_commands.append((lang, commands))
+    else:
+        invalid_lang_compilers.append((lang, compiler))
+
+# We test all language-compiler combinations, just to report what is skipped
+
+def test_C89_cc():
+    if ("C89", 'cc') in invalid_lang_compilers:
+        skip("`cc' command didn't work as expected (C89)")
+
+
+def test_C99_cc():
+    if ("C99", 'cc') in invalid_lang_compilers:
+        skip("`cc' command didn't work as expected (C99)")
+
+
+def test_F95_ifort():
+    if ("F95", 'ifort') in invalid_lang_compilers:
+        skip("`ifort' command didn't work as expected")
+
+
+def test_F95_gfortran():
+    if ("F95", 'gfortran') in invalid_lang_compilers:
+        skip("`gfortran' command didn't work as expected")
+
+
+def test_F95_g95():
+    if ("F95", 'g95') in invalid_lang_compilers:
+        skip("`g95' command didn't work as expected")
+
+# Here comes the actual tests
+
+
+def test_basic_codegen():
+    numerical_tests = [
+        ("test", (1.0, 6.0, 3.0), 21.0, 1e-15),
+        ("test", (-1.0, 2.0, -2.5), -2.5, 1e-15),
+    ]
+    name_expr = [("test", (x + y)*z)]
+    for lang, commands in valid_lang_commands:
+        run_test("basic_codegen", name_expr, numerical_tests, lang, commands)
+
+
+def test_intrinsic_math1_codegen():
+    # not included: log10
+    from sympy.core.evalf import N
+    from sympy.functions import ln
+    from sympy.functions.elementary.exponential import log
+    from sympy.functions.elementary.hyperbolic import (cosh, sinh, tanh)
+    from sympy.functions.elementary.integers import (ceiling, floor)
+    from sympy.functions.elementary.miscellaneous import sqrt
+    from sympy.functions.elementary.trigonometric import (acos, asin, atan, cos, sin, tan)
+    name_expr = [
+        ("test_fabs", abs(x)),
+        ("test_acos", acos(x)),
+        ("test_asin", asin(x)),
+        ("test_atan", atan(x)),
+        ("test_cos", cos(x)),
+        ("test_cosh", cosh(x)),
+        ("test_log", log(x)),
+        ("test_ln", ln(x)),
+        ("test_sin", sin(x)),
+        ("test_sinh", sinh(x)),
+        ("test_sqrt", sqrt(x)),
+        ("test_tan", tan(x)),
+        ("test_tanh", tanh(x)),
+    ]
+    numerical_tests = []
+    for name, expr in name_expr:
+        for xval in 0.2, 0.5, 0.8:
+            expected = N(expr.subs(x, xval))
+            numerical_tests.append((name, (xval,), expected, 1e-14))
+    for lang, commands in valid_lang_commands:
+        if lang.startswith("C"):
+            name_expr_C = [("test_floor", floor(x)), ("test_ceil", ceiling(x))]
+        else:
+            name_expr_C = []
+        run_test("intrinsic_math1", name_expr + name_expr_C,
+                 numerical_tests, lang, commands)
+
+
+def test_instrinsic_math2_codegen():
+    # not included: frexp, ldexp, modf, fmod
+    from sympy.core.evalf import N
+    from sympy.functions.elementary.trigonometric import atan2
+    name_expr = [
+        ("test_atan2", atan2(x, y)),
+        ("test_pow", x**y),
+    ]
+    numerical_tests = []
+    for name, expr in name_expr:
+        for xval, yval in (0.2, 1.3), (0.5, -0.2), (0.8, 0.8):
+            expected = N(expr.subs(x, xval).subs(y, yval))
+            numerical_tests.append((name, (xval, yval), expected, 1e-14))
+    for lang, commands in valid_lang_commands:
+        run_test("intrinsic_math2", name_expr, numerical_tests, lang, commands)
+
+
+def test_complicated_codegen():
+    from sympy.core.evalf import N
+    from sympy.functions.elementary.trigonometric import (cos, sin, tan)
+    name_expr = [
+        ("test1", ((sin(x) + cos(y) + tan(z))**7).expand()),
+        ("test2", cos(cos(cos(cos(cos(cos(cos(cos(x + y + z))))))))),
+    ]
+    numerical_tests = []
+    for name, expr in name_expr:
+        for xval, yval, zval in (0.2, 1.3, -0.3), (0.5, -0.2, 0.0), (0.8, 2.1, 0.8):
+            expected = N(expr.subs(x, xval).subs(y, yval).subs(z, zval))
+            numerical_tests.append((name, (xval, yval, zval), expected, 1e-12))
+    for lang, commands in valid_lang_commands:
+        run_test(
+            "complicated_codegen", name_expr, numerical_tests, lang, commands)

.venv/lib/python3.13/site-packages/sympy/external/tests/test_gmpy.py

@@ -0,0 +1,12 @@
+from sympy.external.gmpy import LONG_MAX, iroot
+from sympy.testing.pytest import raises
+
+
+def test_iroot():
+    assert iroot(2, LONG_MAX) == (1, False)
+    assert iroot(2, LONG_MAX + 1) == (1, False)
+    for x in range(3):
+        assert iroot(x, 1) == (x, True)
+    raises(ValueError, lambda: iroot(-1, 1))
+    raises(ValueError, lambda: iroot(0, 0))
+    raises(ValueError, lambda: iroot(0, -1))

.venv/lib/python3.13/site-packages/sympy/external/tests/test_importtools.py

@@ -0,0 +1,40 @@
+from sympy.external import import_module
+from sympy.testing.pytest import warns
+
+# fixes issue that arose in addressing issue 6533
+def test_no_stdlib_collections():
+    '''
+    make sure we get the right collections when it is not part of a
+    larger list
+    '''
+    import collections
+    matplotlib = import_module('matplotlib',
+        import_kwargs={'fromlist': ['cm', 'collections']},
+        min_module_version='1.1.0', catch=(RuntimeError,))
+    if matplotlib:
+        assert collections != matplotlib.collections
+
+def test_no_stdlib_collections2():
+    '''
+    make sure we get the right collections when it is not part of a
+    larger list
+    '''
+    import collections
+    matplotlib = import_module('matplotlib',
+        import_kwargs={'fromlist': ['collections']},
+        min_module_version='1.1.0', catch=(RuntimeError,))
+    if matplotlib:
+        assert collections != matplotlib.collections
+
+def test_no_stdlib_collections3():
+    '''make sure we get the right collections with no catch'''
+    import collections
+    matplotlib = import_module('matplotlib',
+        import_kwargs={'fromlist': ['cm', 'collections']},
+        min_module_version='1.1.0')
+    if matplotlib:
+        assert collections != matplotlib.collections
+
+def test_min_module_version_python3_basestring_error():
+    with warns(UserWarning):
+        import_module('mpmath', min_module_version='1000.0.1')

.venv/lib/python3.13/site-packages/sympy/external/tests/test_ntheory.py

@@ -0,0 +1,307 @@
+from itertools import permutations
+
+from sympy.external.ntheory import (bit_scan1, remove, bit_scan0, is_fermat_prp,
+                                    is_euler_prp, is_strong_prp, gcdext, _lucas_sequence,
+                                    is_fibonacci_prp, is_lucas_prp, is_selfridge_prp,
+                                    is_strong_lucas_prp, is_strong_selfridge_prp,
+                                    is_bpsw_prp, is_strong_bpsw_prp)
+from sympy.testing.pytest import raises
+
+
+def test_bit_scan1():
+    assert bit_scan1(0) is None
+    assert bit_scan1(1) == 0
+    assert bit_scan1(-1) == 0
+    assert bit_scan1(2) == 1
+    assert bit_scan1(7) == 0
+    assert bit_scan1(-7) == 0
+    for i in range(100):
+        assert bit_scan1(1 << i) == i
+        assert bit_scan1((1 << i) * 31337) == i
+    for i in range(500):
+        n = (1 << 500) + (1 << i)
+        assert bit_scan1(n) == i
+    assert bit_scan1(1 << 1000001) == 1000001
+    assert bit_scan1((1 << 273956)*7**37) == 273956
+    # issue 12709
+    for i in range(1, 10):
+        big = 1 << i
+        assert bit_scan1(-big) == bit_scan1(big)
+
+
+def test_bit_scan0():
+    assert bit_scan0(-1) is None
+    assert bit_scan0(0) == 0
+    assert bit_scan0(1) == 1
+    assert bit_scan0(-2) == 0
+
+
+def test_remove():
+    raises(ValueError, lambda: remove(1, 1))
+    assert remove(0, 3) == (0, 0)
+    for f in range(2, 10):
+        for y in range(2, 1000):
+            for z in [1, 17, 101, 1009]:
+                assert remove(z*f**y, f) == (z, y)
+
+
+def test_gcdext():
+    assert gcdext(0, 0) == (0, 0, 0)
+    assert gcdext(3, 0) == (3, 1, 0)
+    assert gcdext(0, 4) == (4, 0, 1)
+
+    for n in range(1, 10):
+        assert gcdext(n, 1) == gcdext(-n, 1) == (1, 0, 1)
+        assert gcdext(n, -1) == gcdext(-n, -1) == (1, 0, -1)
+        assert gcdext(n, n) == gcdext(-n, n) == (n, 0, 1)
+        assert gcdext(n, -n) == gcdext(-n, -n) == (n, 0, -1)
+
+    for n in range(2, 10):
+        assert gcdext(1, n) == gcdext(1, -n) == (1, 1, 0)
+        assert gcdext(-1, n) == gcdext(-1, -n) == (1, -1, 0)
+
+    for a, b in permutations([2**5, 3, 5, 7**2, 11], 2):
+        g, x, y = gcdext(a, b)
+        assert g == a*x + b*y == 1
+
+
+def test_is_fermat_prp():
+    # invalid input
+    raises(ValueError, lambda: is_fermat_prp(0, 10))
+    raises(ValueError, lambda: is_fermat_prp(5, 1))
+
+    # n = 1
+    assert not is_fermat_prp(1, 3)
+
+    # n is prime
+    assert is_fermat_prp(2, 4)
+    assert is_fermat_prp(3, 2)
+    assert is_fermat_prp(11, 3)
+    assert is_fermat_prp(2**31-1, 5)
+
+    # A001567
+    pseudorpime = [341, 561, 645, 1105, 1387, 1729, 1905, 2047,
+                   2465, 2701, 2821, 3277, 4033, 4369, 4371, 4681]
+    for n in pseudorpime:
+        assert is_fermat_prp(n, 2)
+
+    # A020136
+    pseudorpime = [15, 85, 91, 341, 435, 451, 561, 645, 703, 1105,
+                   1247, 1271, 1387, 1581, 1695, 1729, 1891, 1905]
+    for n in pseudorpime:
+        assert is_fermat_prp(n, 4)
+
+
+def test_is_euler_prp():
+    # invalid input
+    raises(ValueError, lambda: is_euler_prp(0, 10))
+    raises(ValueError, lambda: is_euler_prp(5, 1))
+
+    # n = 1
+    assert not is_euler_prp(1, 3)
+
+    # n is prime
+    assert is_euler_prp(2, 4)
+    assert is_euler_prp(3, 2)
+    assert is_euler_prp(11, 3)
+    assert is_euler_prp(2**31-1, 5)
+
+    # A047713
+    pseudorpime = [561, 1105, 1729, 1905, 2047, 2465, 3277, 4033,
+                   4681, 6601, 8321, 8481, 10585, 12801, 15841]
+    for n in pseudorpime:
+        assert is_euler_prp(n, 2)
+
+    # A048950
+    pseudorpime = [121, 703, 1729, 1891, 2821, 3281, 7381, 8401,
+                   8911, 10585, 12403, 15457, 15841, 16531, 18721]
+    for n in pseudorpime:
+        assert is_euler_prp(n, 3)
+
+
+def test_is_strong_prp():
+    # invalid input
+    raises(ValueError, lambda: is_strong_prp(0, 10))
+    raises(ValueError, lambda: is_strong_prp(5, 1))
+
+    # n = 1
+    assert not is_strong_prp(1, 3)
+
+    # n is prime
+    assert is_strong_prp(2, 4)
+    assert is_strong_prp(3, 2)
+    assert is_strong_prp(11, 3)
+    assert is_strong_prp(2**31-1, 5)
+
+    # A001262
+    pseudorpime = [2047, 3277, 4033, 4681, 8321, 15841, 29341,
+                   42799, 49141, 52633, 65281, 74665, 80581]
+    for n in pseudorpime:
+        assert is_strong_prp(n, 2)
+
+    # A020229
+    pseudorpime = [121, 703, 1891, 3281, 8401, 8911, 10585, 12403,
+                   16531, 18721, 19345, 23521, 31621, 44287, 47197]
+    for n in pseudorpime:
+        assert is_strong_prp(n, 3)
+
+
+def test_lucas_sequence():
+    def lucas_u(P, Q, length):
+        array = [0] * length
+        array[1] = 1
+        for k in range(2, length):
+            array[k] = P * array[k - 1] - Q * array[k - 2]
+        return array
+
+    def lucas_v(P, Q, length):
+        array = [0] * length
+        array[0] = 2
+        array[1] = P
+        for k in range(2, length):
+            array[k] = P * array[k - 1] - Q * array[k - 2]
+        return array
+
+    length = 20
+    for P in range(-10, 10):
+        for Q in range(-10, 10):
+            D = P**2 - 4*Q
+            if D == 0:
+                continue
+            us = lucas_u(P, Q, length)
+            vs = lucas_v(P, Q, length)
+            for n in range(3, 100, 2):
+                for k in range(length):
+                    U, V, Qk = _lucas_sequence(n, P, Q, k)
+                    assert U == us[k] % n
+                    assert V == vs[k] % n
+                    assert pow(Q, k, n) == Qk
+
+
+def test_is_fibonacci_prp():
+    # invalid input
+    raises(ValueError, lambda: is_fibonacci_prp(3, 2, 1))
+    raises(ValueError, lambda: is_fibonacci_prp(3, -5, 1))
+    raises(ValueError, lambda: is_fibonacci_prp(3, 5, 2))
+    raises(ValueError, lambda: is_fibonacci_prp(0, 5, -1))
+
+    # n = 1
+    assert not is_fibonacci_prp(1, 3, 1)
+
+    # n is prime
+    assert is_fibonacci_prp(2, 5, 1)
+    assert is_fibonacci_prp(3, 6, -1)
+    assert is_fibonacci_prp(11, 7, 1)
+    assert is_fibonacci_prp(2**31-1, 8, -1)
+
+    # A005845
+    pseudorpime = [705, 2465, 2737, 3745, 4181, 5777, 6721,
+                   10877, 13201, 15251, 24465, 29281, 34561]
+    for n in pseudorpime:
+        assert is_fibonacci_prp(n, 1, -1)
+
+
+def test_is_lucas_prp():
+    # invalid input
+    raises(ValueError, lambda: is_lucas_prp(3, 2, 1))
+    raises(ValueError, lambda: is_lucas_prp(0, 5, -1))
+    raises(ValueError, lambda: is_lucas_prp(15, 3, 1))
+
+    # n = 1
+    assert not is_lucas_prp(1, 3, 1)
+
+    # n is prime
+    assert is_lucas_prp(2, 5, 2)
+    assert is_lucas_prp(3, 6, -1)
+    assert is_lucas_prp(11, 7, 5)
+    assert is_lucas_prp(2**31-1, 8, -3)
+
+    # A081264
+    pseudorpime = [323, 377, 1891, 3827, 4181, 5777, 6601, 6721,
+                   8149, 10877, 11663, 13201, 13981, 15251, 17119]
+    for n in pseudorpime:
+        assert is_lucas_prp(n, 1, -1)
+
+
+def test_is_selfridge_prp():
+    # invalid input
+    raises(ValueError, lambda: is_selfridge_prp(0))
+
+    # n = 1
+    assert not is_selfridge_prp(1)
+
+    # n is prime
+    assert is_selfridge_prp(2)
+    assert is_selfridge_prp(3)
+    assert is_selfridge_prp(11)
+    assert is_selfridge_prp(2**31-1)
+
+    # A217120
+    pseudorpime = [323, 377, 1159, 1829, 3827, 5459, 5777, 9071,
+                   9179, 10877, 11419, 11663, 13919, 14839, 16109]
+    for n in pseudorpime:
+        assert is_selfridge_prp(n)
+
+
+def test_is_strong_lucas_prp():
+    # invalid input
+    raises(ValueError, lambda: is_strong_lucas_prp(3, 2, 1))
+    raises(ValueError, lambda: is_strong_lucas_prp(0, 5, -1))
+    raises(ValueError, lambda: is_strong_lucas_prp(15, 3, 1))
+
+    # n = 1
+    assert not is_strong_lucas_prp(1, 3, 1)
+
+    # n is prime
+    assert is_strong_lucas_prp(2, 5, 2)
+    assert is_strong_lucas_prp(3, 6, -1)
+    assert is_strong_lucas_prp(11, 7, 5)
+    assert is_strong_lucas_prp(2**31-1, 8, -3)
+
+
+def test_is_strong_selfridge_prp():
+    # invalid input
+    raises(ValueError, lambda: is_strong_selfridge_prp(0))
+
+    # n = 1
+    assert not is_strong_selfridge_prp(1)
+
+    # n is prime
+    assert is_strong_selfridge_prp(2)
+    assert is_strong_selfridge_prp(3)
+    assert is_strong_selfridge_prp(11)
+    assert is_strong_selfridge_prp(2**31-1)
+
+    # A217255
+    pseudorpime = [5459, 5777, 10877, 16109, 18971, 22499, 24569,
+                   25199, 40309, 58519, 75077, 97439, 100127, 113573]
+    for n in pseudorpime:
+        assert is_strong_selfridge_prp(n)
+
+
+def test_is_bpsw_prp():
+    # invalid input
+    raises(ValueError, lambda: is_bpsw_prp(0))
+
+    # n = 1
+    assert not is_bpsw_prp(1)
+
+    # n is prime
+    assert is_bpsw_prp(2)
+    assert is_bpsw_prp(3)
+    assert is_bpsw_prp(11)
+    assert is_bpsw_prp(2**31-1)
+
+
+def test_is_strong_bpsw_prp():
+    # invalid input
+    raises(ValueError, lambda: is_strong_bpsw_prp(0))
+
+    # n = 1
+    assert not is_strong_bpsw_prp(1)
+
+    # n is prime
+    assert is_strong_bpsw_prp(2)
+    assert is_strong_bpsw_prp(3)
+    assert is_strong_bpsw_prp(11)
+    assert is_strong_bpsw_prp(2**31-1)

.venv/lib/python3.13/site-packages/sympy/external/tests/test_numpy.py

@@ -0,0 +1,335 @@
+# This testfile tests SymPy <-> NumPy compatibility
+
+# Don't test any SymPy features here. Just pure interaction with NumPy.
+# Always write regular SymPy tests for anything, that can be tested in pure
+# Python (without numpy). Here we test everything, that a user may need when
+# using SymPy with NumPy
+from sympy.external.importtools import version_tuple
+from sympy.external import import_module
+
+numpy = import_module('numpy')
+if numpy:
+    array, matrix, ndarray = numpy.array, numpy.matrix, numpy.ndarray
+else:
+    #bin/test will not execute any tests now
+    disabled = True
+
+
+from sympy.core.numbers import (Float, Integer, Rational)
+from sympy.core.symbol import (Symbol, symbols)
+from sympy.functions.elementary.trigonometric import sin
+from sympy.matrices.dense import (Matrix, list2numpy, matrix2numpy, symarray)
+from sympy.utilities.lambdify import lambdify
+import sympy
+
+import mpmath
+from sympy.abc import x, y, z
+from sympy.utilities.decorator import conserve_mpmath_dps
+from sympy.utilities.exceptions import ignore_warnings
+from sympy.testing.pytest import raises
+
+
+# first, systematically check, that all operations are implemented and don't
+# raise an exception
+
+
+def test_systematic_basic():
+    def s(sympy_object, numpy_array):
+        _ = [sympy_object + numpy_array,
+        numpy_array + sympy_object,
+        sympy_object - numpy_array,
+        numpy_array - sympy_object,
+        sympy_object * numpy_array,
+        numpy_array * sympy_object,
+        sympy_object / numpy_array,
+        numpy_array / sympy_object,
+        sympy_object ** numpy_array,
+        numpy_array ** sympy_object]
+    x = Symbol("x")
+    y = Symbol("y")
+    sympy_objs = [
+        Rational(2, 3),
+        Float("1.3"),
+        x,
+        y,
+        pow(x, y)*y,
+        Integer(5),
+        Float(5.5),
+    ]
+    numpy_objs = [
+        array([1]),
+        array([3, 8, -1]),
+        array([x, x**2, Rational(5)]),
+        array([x/y*sin(y), 5, Rational(5)]),
+    ]
+    for x in sympy_objs:
+        for y in numpy_objs:
+            s(x, y)
+
+
+# now some random tests, that test particular problems and that also
+# check that the results of the operations are correct
+
+def test_basics():
+    one = Rational(1)
+    zero = Rational(0)
+    assert array(1) == array(one)
+    assert array([one]) == array([one])
+    assert array([x]) == array([x])
+    assert array(x) == array(Symbol("x"))
+    assert array(one + x) == array(1 + x)
+
+    X = array([one, zero, zero])
+    assert (X == array([one, zero, zero])).all()
+    assert (X == array([one, 0, 0])).all()
+
+
+def test_arrays():
+    one = Rational(1)
+    zero = Rational(0)
+    X = array([one, zero, zero])
+    Y = one*X
+    X = array([Symbol("a") + Rational(1, 2)])
+    Y = X + X
+    assert Y == array([1 + 2*Symbol("a")])
+    Y = Y + 1
+    assert Y == array([2 + 2*Symbol("a")])
+    Y = X - X
+    assert Y == array([0])
+
+
+def test_conversion1():
+    a = list2numpy([x**2, x])
+    #looks like an array?
+    assert isinstance(a, ndarray)
+    assert a[0] == x**2
+    assert a[1] == x
+    assert len(a) == 2
+    #yes, it's the array
+
+
+def test_conversion2():
+    a = 2*list2numpy([x**2, x])
+    b = list2numpy([2*x**2, 2*x])
+    assert (a == b).all()
+
+    one = Rational(1)
+    zero = Rational(0)
+    X = list2numpy([one, zero, zero])
+    Y = one*X
+    X = list2numpy([Symbol("a") + Rational(1, 2)])
+    Y = X + X
+    assert Y == array([1 + 2*Symbol("a")])
+    Y = Y + 1
+    assert Y == array([2 + 2*Symbol("a")])
+    Y = X - X
+    assert Y == array([0])
+
+
+def test_list2numpy():
+    assert (array([x**2, x]) == list2numpy([x**2, x])).all()
+
+
+def test_Matrix1():
+    m = Matrix([[x, x**2], [5, 2/x]])
+    assert (array(m.subs(x, 2)) == array([[2, 4], [5, 1]])).all()
+    m = Matrix([[sin(x), x**2], [5, 2/x]])
+    assert (array(m.subs(x, 2)) == array([[sin(2), 4], [5, 1]])).all()
+
+
+def test_Matrix2():
+    m = Matrix([[x, x**2], [5, 2/x]])
+    with ignore_warnings(PendingDeprecationWarning):
+        assert (matrix(m.subs(x, 2)) == matrix([[2, 4], [5, 1]])).all()
+    m = Matrix([[sin(x), x**2], [5, 2/x]])
+    with ignore_warnings(PendingDeprecationWarning):
+        assert (matrix(m.subs(x, 2)) == matrix([[sin(2), 4], [5, 1]])).all()
+
+
+def test_Matrix3():
+    a = array([[2, 4], [5, 1]])
+    assert Matrix(a) == Matrix([[2, 4], [5, 1]])
+    assert Matrix(a) != Matrix([[2, 4], [5, 2]])
+    a = array([[sin(2), 4], [5, 1]])
+    assert Matrix(a) == Matrix([[sin(2), 4], [5, 1]])
+    assert Matrix(a) != Matrix([[sin(0), 4], [5, 1]])
+
+
+def test_Matrix4():
+    with ignore_warnings(PendingDeprecationWarning):
+        a = matrix([[2, 4], [5, 1]])
+    assert Matrix(a) == Matrix([[2, 4], [5, 1]])
+    assert Matrix(a) != Matrix([[2, 4], [5, 2]])
+    with ignore_warnings(PendingDeprecationWarning):
+        a = matrix([[sin(2), 4], [5, 1]])
+    assert Matrix(a) == Matrix([[sin(2), 4], [5, 1]])
+    assert Matrix(a) != Matrix([[sin(0), 4], [5, 1]])
+
+
+def test_Matrix_sum():
+    M = Matrix([[1, 2, 3], [x, y, x], [2*y, -50, z*x]])
+    with ignore_warnings(PendingDeprecationWarning):
+        m = matrix([[2, 3, 4], [x, 5, 6], [x, y, z**2]])
+    assert M + m == Matrix([[3, 5, 7], [2*x, y + 5, x + 6], [2*y + x, y - 50, z*x + z**2]])
+    assert m + M == Matrix([[3, 5, 7], [2*x, y + 5, x + 6], [2*y + x, y - 50, z*x + z**2]])
+    assert M + m == M.add(m)
+
+
+def test_Matrix_mul():
+    M = Matrix([[1, 2, 3], [x, y, x]])
+    with ignore_warnings(PendingDeprecationWarning):
+        m = matrix([[2, 4], [x, 6], [x, z**2]])
+    assert M*m == Matrix([
+        [         2 + 5*x,        16 + 3*z**2],
+        [2*x + x*y + x**2, 4*x + 6*y + x*z**2],
+    ])
+
+    assert m*M == Matrix([
+        [   2 + 4*x,      4 + 4*y,      6 + 4*x],
+        [       7*x,    2*x + 6*y,          9*x],
+        [x + x*z**2, 2*x + y*z**2, 3*x + x*z**2],
+    ])
+    a = array([2])
+    assert a[0] * M == 2 * M
+    assert M * a[0] == 2 * M
+
+
+def test_Matrix_array():
+    class matarray:
+        def __array__(self, dtype=object, copy=None):
+            if copy is not None and not copy:
+                raise TypeError("Cannot implement copy=False when converting Matrix to ndarray")
+            from numpy import array
+            return array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+    matarr = matarray()
+    assert Matrix(matarr) == Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+
+
+def test_matrix2numpy():
+    a = matrix2numpy(Matrix([[1, x**2], [3*sin(x), 0]]))
+    assert isinstance(a, ndarray)
+    assert a.shape == (2, 2)
+    assert a[0, 0] == 1
+    assert a[0, 1] == x**2
+    assert a[1, 0] == 3*sin(x)
+    assert a[1, 1] == 0
+
+
+def test_matrix2numpy_conversion():
+    a = Matrix([[1, 2, sin(x)], [x**2, x, Rational(1, 2)]])
+    b = array([[1, 2, sin(x)], [x**2, x, Rational(1, 2)]])
+    assert (matrix2numpy(a) == b).all()
+    assert matrix2numpy(a).dtype == numpy.dtype('object')
+
+    c = matrix2numpy(Matrix([[1, 2], [10, 20]]), dtype='int8')
+    d = matrix2numpy(Matrix([[1, 2], [10, 20]]), dtype='float64')
+    assert c.dtype == numpy.dtype('int8')
+    assert d.dtype == numpy.dtype('float64')
+
+
+def test_issue_3728():
+    assert (Rational(1, 2)*array([2*x, 0]) == array([x, 0])).all()
+    assert (Rational(1, 2) + array(
+        [2*x, 0]) == array([2*x + Rational(1, 2), Rational(1, 2)])).all()
+    assert (Float("0.5")*array([2*x, 0]) == array([Float("1.0")*x, 0])).all()
+    assert (Float("0.5") + array(
+        [2*x, 0]) == array([2*x + Float("0.5"), Float("0.5")])).all()
+
+
+@conserve_mpmath_dps
+def test_lambdify():
+    mpmath.mp.dps = 16
+    sin02 = mpmath.mpf("0.198669330795061215459412627")
+    f = lambdify(x, sin(x), "numpy")
+    prec = 1e-15
+    assert -prec < f(0.2) - sin02 < prec
+
+    # if this succeeds, it can't be a numpy function
+
+    if version_tuple(numpy.__version__) >= version_tuple('1.17'):
+        with raises(TypeError):
+            f(x)
+    else:
+        with raises(AttributeError):
+            f(x)
+
+
+def test_lambdify_matrix():
+    f = lambdify(x, Matrix([[x, 2*x], [1, 2]]), [{'ImmutableMatrix': numpy.array}, "numpy"])
+    assert (f(1) == array([[1, 2], [1, 2]])).all()
+
+
+def test_lambdify_matrix_multi_input():
+    M = sympy.Matrix([[x**2, x*y, x*z],
+                      [y*x, y**2, y*z],
+                      [z*x, z*y, z**2]])
+    f = lambdify((x, y, z), M, [{'ImmutableMatrix': numpy.array}, "numpy"])
+
+    xh, yh, zh = 1.0, 2.0, 3.0
+    expected = array([[xh**2, xh*yh, xh*zh],
+                      [yh*xh, yh**2, yh*zh],
+                      [zh*xh, zh*yh, zh**2]])
+    actual = f(xh, yh, zh)
+    assert numpy.allclose(actual, expected)
+
+
+def test_lambdify_matrix_vec_input():
+    X = sympy.DeferredVector('X')
+    M = Matrix([
+        [X[0]**2, X[0]*X[1], X[0]*X[2]],
+        [X[1]*X[0], X[1]**2, X[1]*X[2]],
+        [X[2]*X[0], X[2]*X[1], X[2]**2]])
+    f = lambdify(X, M, [{'ImmutableMatrix': numpy.array}, "numpy"])
+
+    Xh = array([1.0, 2.0, 3.0])
+    expected = array([[Xh[0]**2, Xh[0]*Xh[1], Xh[0]*Xh[2]],
+                      [Xh[1]*Xh[0], Xh[1]**2, Xh[1]*Xh[2]],
+                      [Xh[2]*Xh[0], Xh[2]*Xh[1], Xh[2]**2]])
+    actual = f(Xh)
+    assert numpy.allclose(actual, expected)
+
+
+def test_lambdify_transl():
+    from sympy.utilities.lambdify import NUMPY_TRANSLATIONS
+    for sym, mat in NUMPY_TRANSLATIONS.items():
+        assert sym in sympy.__dict__
+        assert mat in numpy.__dict__
+
+
+def test_symarray():
+    """Test creation of numpy arrays of SymPy symbols."""
+
+    import numpy as np
+    import numpy.testing as npt
+
+    syms = symbols('_0,_1,_2')
+    s1 = symarray("", 3)
+    s2 = symarray("", 3)
+    npt.assert_array_equal(s1, np.array(syms, dtype=object))
+    assert s1[0] == s2[0]
+
+    a = symarray('a', 3)
+    b = symarray('b', 3)
+    assert not(a[0] == b[0])
+
+    asyms = symbols('a_0,a_1,a_2')
+    npt.assert_array_equal(a, np.array(asyms, dtype=object))
+
+    # Multidimensional checks
+    a2d = symarray('a', (2, 3))
+    assert a2d.shape == (2, 3)
+    a00, a12 = symbols('a_0_0,a_1_2')
+    assert a2d[0, 0] == a00
+    assert a2d[1, 2] == a12
+
+    a3d = symarray('a', (2, 3, 2))
+    assert a3d.shape == (2, 3, 2)
+    a000, a120, a121 = symbols('a_0_0_0,a_1_2_0,a_1_2_1')
+    assert a3d[0, 0, 0] == a000
+    assert a3d[1, 2, 0] == a120
+    assert a3d[1, 2, 1] == a121
+
+
+def test_vectorize():
+    assert (numpy.vectorize(
+        sin)([1, 2, 3]) == numpy.array([sin(1), sin(2), sin(3)])).all()

.venv/lib/python3.13/site-packages/sympy/external/tests/test_pythonmpq.py

@@ -0,0 +1,176 @@
+"""
+test_pythonmpq.py
+
+Test the PythonMPQ class for consistency with gmpy2's mpq type. If gmpy2 is
+installed run the same tests for both.
+"""
+from fractions import Fraction
+from decimal import Decimal
+import pickle
+from typing import Callable, List, Tuple, Type
+
+from sympy.testing.pytest import raises
+
+from sympy.external.pythonmpq import PythonMPQ
+
+#
+# If gmpy2 is installed then run the tests for both mpq and PythonMPQ.
+# That should ensure consistency between the implementation here and mpq.
+#
+rational_types: List[Tuple[Callable, Type, Callable, Type]]
+rational_types = [(PythonMPQ, PythonMPQ, int, int)]
+try:
+    from gmpy2 import mpq, mpz
+    rational_types.append((mpq, type(mpq(1)), mpz, type(mpz(1))))
+except ImportError:
+    pass
+
+
+def test_PythonMPQ():
+    #
+    # Test PythonMPQ and also mpq if gmpy/gmpy2 is installed.
+    #
+    for Q, TQ, Z, TZ in rational_types:
+
+        def check_Q(q):
+            assert isinstance(q, TQ)
+            assert isinstance(q.numerator, TZ)
+            assert isinstance(q.denominator, TZ)
+            return q.numerator, q.denominator
+
+        # Check construction from different types
+        assert check_Q(Q(3)) == (3, 1)
+        assert check_Q(Q(3, 5)) == (3, 5)
+        assert check_Q(Q(Q(3, 5))) == (3, 5)
+        assert check_Q(Q(0.5)) == (1, 2)
+        assert check_Q(Q('0.5')) == (1, 2)
+        assert check_Q(Q(Fraction(3, 5))) == (3, 5)
+
+        # https://github.com/aleaxit/gmpy/issues/327
+        if Q is PythonMPQ:
+            assert check_Q(Q(Decimal('0.6'))) == (3, 5)
+
+        # Invalid types
+        raises(TypeError, lambda: Q([]))
+        raises(TypeError, lambda: Q([], []))
+
+        # Check normalisation of signs
+        assert check_Q(Q(2, 3)) == (2, 3)
+        assert check_Q(Q(-2, 3)) == (-2, 3)
+        assert check_Q(Q(2, -3)) == (-2, 3)
+        assert check_Q(Q(-2, -3)) == (2, 3)
+
+        # Check gcd calculation
+        assert check_Q(Q(12, 8)) == (3, 2)
+
+        # __int__/__float__
+        assert int(Q(5, 3)) == 1
+        assert int(Q(-5, 3)) == -1
+        assert float(Q(5, 2)) == 2.5
+        assert float(Q(-5, 2)) == -2.5
+
+        # __str__/__repr__
+        assert str(Q(2, 1)) == "2"
+        assert str(Q(1, 2)) == "1/2"
+        if Q is PythonMPQ:
+            assert repr(Q(2, 1)) == "MPQ(2,1)"
+            assert repr(Q(1, 2)) == "MPQ(1,2)"
+        else:
+            assert repr(Q(2, 1)) == "mpq(2,1)"
+            assert repr(Q(1, 2)) == "mpq(1,2)"
+
+        # __bool__
+        assert bool(Q(1, 2)) is True
+        assert bool(Q(0)) is False
+
+        # __eq__/__ne__
+        assert (Q(2, 3) == Q(2, 3)) is True
+        assert (Q(2, 3) == Q(2, 5)) is False
+        assert (Q(2, 3) != Q(2, 3)) is False
+        assert (Q(2, 3) != Q(2, 5)) is True
+
+        # __hash__
+        assert hash(Q(3, 5)) == hash(Fraction(3, 5))
+
+        # __reduce__
+        q = Q(2, 3)
+        assert pickle.loads(pickle.dumps(q)) == q
+
+        # __ge__/__gt__/__le__/__lt__
+        assert (Q(1, 3) < Q(2, 3)) is True
+        assert (Q(2, 3) < Q(2, 3)) is False
+        assert (Q(2, 3) < Q(1, 3)) is False
+        assert (Q(-2, 3) < Q(1, 3)) is True
+        assert (Q(1, 3) < Q(-2, 3)) is False
+
+        assert (Q(1, 3) <= Q(2, 3)) is True
+        assert (Q(2, 3) <= Q(2, 3)) is True
+        assert (Q(2, 3) <= Q(1, 3)) is False
+        assert (Q(-2, 3) <= Q(1, 3)) is True
+        assert (Q(1, 3) <= Q(-2, 3)) is False
+
+        assert (Q(1, 3) > Q(2, 3)) is False
+        assert (Q(2, 3) > Q(2, 3)) is False
+        assert (Q(2, 3) > Q(1, 3)) is True
+        assert (Q(-2, 3) > Q(1, 3)) is False
+        assert (Q(1, 3) > Q(-2, 3)) is True
+
+        assert (Q(1, 3) >= Q(2, 3)) is False
+        assert (Q(2, 3) >= Q(2, 3)) is True
+        assert (Q(2, 3) >= Q(1, 3)) is True
+        assert (Q(-2, 3) >= Q(1, 3)) is False
+        assert (Q(1, 3) >= Q(-2, 3)) is True
+
+        # __abs__/__pos__/__neg__
+        assert abs(Q(2, 3)) == abs(Q(-2, 3)) == Q(2, 3)
+        assert +Q(2, 3) == Q(2, 3)
+        assert -Q(2, 3) == Q(-2, 3)
+
+        # __add__/__radd__
+        assert Q(2, 3) + Q(5, 7) == Q(29, 21)
+        assert Q(2, 3) + 1 == Q(5, 3)
+        assert 1 + Q(2, 3) == Q(5, 3)
+        raises(TypeError, lambda: [] + Q(1))
+        raises(TypeError, lambda: Q(1) + [])
+
+        # __sub__/__rsub__
+        assert Q(2, 3) - Q(5, 7) == Q(-1, 21)
+        assert Q(2, 3) - 1 == Q(-1, 3)
+        assert 1 - Q(2, 3) == Q(1, 3)
+        raises(TypeError, lambda: [] - Q(1))
+        raises(TypeError, lambda: Q(1) - [])
+
+        # __mul__/__rmul__
+        assert Q(2, 3) * Q(5, 7) == Q(10, 21)
+        assert Q(2, 3) * 1 == Q(2, 3)
+        assert 1 * Q(2, 3) == Q(2, 3)
+        raises(TypeError, lambda: [] * Q(1))
+        raises(TypeError, lambda: Q(1) * [])
+
+        # __pow__/__rpow__
+        assert Q(2, 3) ** 2 == Q(4, 9)
+        assert Q(2, 3) ** 1 == Q(2, 3)
+        assert Q(-2, 3) ** 2 == Q(4, 9)
+        assert Q(-2, 3) ** -1 == Q(-3, 2)
+        if Q is PythonMPQ:
+            raises(TypeError, lambda: 1 ** Q(2, 3))
+            raises(TypeError, lambda: Q(1, 4) ** Q(1, 2))
+        raises(TypeError, lambda: [] ** Q(1))
+        raises(TypeError, lambda: Q(1) ** [])
+
+        # __div__/__rdiv__
+        assert Q(2, 3) / Q(5, 7) == Q(14, 15)
+        assert Q(2, 3) / 1 == Q(2, 3)
+        assert 1 / Q(2, 3) == Q(3, 2)
+        raises(TypeError, lambda: [] / Q(1))
+        raises(TypeError, lambda: Q(1) / [])
+        raises(ZeroDivisionError, lambda: Q(1, 2) / Q(0))
+
+        # __divmod__
+        if Q is PythonMPQ:
+            raises(TypeError, lambda: Q(2, 3) // Q(1, 3))
+            raises(TypeError, lambda: Q(2, 3) % Q(1, 3))
+            raises(TypeError, lambda: 1 // Q(1, 3))
+            raises(TypeError, lambda: 1 % Q(1, 3))
+            raises(TypeError, lambda: Q(2, 3) // 1)
+            raises(TypeError, lambda: Q(2, 3) % 1)

.venv/lib/python3.13/site-packages/sympy/external/tests/test_scipy.py

@@ -0,0 +1,35 @@
+# This testfile tests SymPy <-> SciPy compatibility
+
+# Don't test any SymPy features here. Just pure interaction with SciPy.
+# Always write regular SymPy tests for anything, that can be tested in pure
+# Python (without scipy). Here we test everything, that a user may need when
+# using SymPy with SciPy
+
+from sympy.external import import_module
+
+scipy = import_module('scipy')
+if not scipy:
+    #bin/test will not execute any tests now
+    disabled = True
+
+from sympy.functions.special.bessel import jn_zeros
+
+
+def eq(a, b, tol=1e-6):
+    for x, y in zip(a, b):
+        if not (abs(x - y) < tol):
+            return False
+    return True
+
+
+def test_jn_zeros():
+    assert eq(jn_zeros(0, 4, method="scipy"),
+            [3.141592, 6.283185, 9.424777, 12.566370])
+    assert eq(jn_zeros(1, 4, method="scipy"),
+            [4.493409, 7.725251, 10.904121, 14.066193])
+    assert eq(jn_zeros(2, 4, method="scipy"),
+            [5.763459, 9.095011, 12.322940, 15.514603])
+    assert eq(jn_zeros(3, 4, method="scipy"),
+            [6.987932, 10.417118, 13.698023, 16.923621])
+    assert eq(jn_zeros(4, 4, method="scipy"),
+            [8.182561, 11.704907, 15.039664, 18.301255])

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

@@ -0,0 +1,115 @@
+"""A functions module, includes all the standard functions.
+
+Combinatorial - factorial, fibonacci, harmonic, bernoulli...
+Elementary - hyperbolic, trigonometric, exponential, floor and ceiling, sqrt...
+Special - gamma, zeta,spherical harmonics...
+"""
+
+from sympy.functions.combinatorial.factorials import (factorial, factorial2,
+        rf, ff, binomial, RisingFactorial, FallingFactorial, subfactorial)
+from sympy.functions.combinatorial.numbers import (carmichael, fibonacci, lucas, tribonacci,
+        harmonic, bernoulli, bell, euler, catalan, genocchi, andre, partition, divisor_sigma,
+        udivisor_sigma, legendre_symbol, jacobi_symbol, kronecker_symbol, mobius,
+        primenu, primeomega, totient, reduced_totient, primepi, motzkin)
+from sympy.functions.elementary.miscellaneous import (sqrt, root, Min, Max,
+        Id, real_root, cbrt, Rem)
+from sympy.functions.elementary.complexes import (re, im, sign, Abs,
+        conjugate, arg, polar_lift, periodic_argument, unbranched_argument,
+        principal_branch, transpose, adjoint, polarify, unpolarify)
+from sympy.functions.elementary.trigonometric import (sin, cos, tan,
+        sec, csc, cot, sinc, asin, acos, atan, asec, acsc, acot, atan2)
+from sympy.functions.elementary.exponential import (exp_polar, exp, log,
+        LambertW)
+from sympy.functions.elementary.hyperbolic import (sinh, cosh, tanh, coth,
+        sech, csch, asinh, acosh, atanh, acoth, asech, acsch)
+from sympy.functions.elementary.integers import floor, ceiling, frac
+from sympy.functions.elementary.piecewise import (Piecewise, piecewise_fold,
+                                                  piecewise_exclusive)
+from sympy.functions.special.error_functions import (erf, erfc, erfi, erf2,
+        erfinv, erfcinv, erf2inv, Ei, expint, E1, li, Li, Si, Ci, Shi, Chi,
+        fresnels, fresnelc)
+from sympy.functions.special.gamma_functions import (gamma, lowergamma,
+        uppergamma, polygamma, loggamma, digamma, trigamma, multigamma)
+from sympy.functions.special.zeta_functions import (dirichlet_eta, zeta,
+        lerchphi, polylog, stieltjes, riemann_xi)
+from sympy.functions.special.tensor_functions import (Eijk, LeviCivita,
+        KroneckerDelta)
+from sympy.functions.special.singularity_functions import SingularityFunction
+from sympy.functions.special.delta_functions import DiracDelta, Heaviside
+from sympy.functions.special.bsplines import bspline_basis, bspline_basis_set, interpolating_spline
+from sympy.functions.special.bessel import (besselj, bessely, besseli, besselk,
+        hankel1, hankel2, jn, yn, jn_zeros, hn1, hn2, airyai, airybi, airyaiprime, airybiprime, marcumq)
+from sympy.functions.special.hyper import hyper, meijerg, appellf1
+from sympy.functions.special.polynomials import (legendre, assoc_legendre,
+        hermite, hermite_prob, chebyshevt, chebyshevu, chebyshevu_root,
+        chebyshevt_root, laguerre, assoc_laguerre, gegenbauer, jacobi, jacobi_normalized)
+from sympy.functions.special.spherical_harmonics import Ynm, Ynm_c, Znm
+from sympy.functions.special.elliptic_integrals import (elliptic_k,
+        elliptic_f, elliptic_e, elliptic_pi)
+from sympy.functions.special.beta_functions import beta, betainc, betainc_regularized
+from sympy.functions.special.mathieu_functions import (mathieus, mathieuc,
+        mathieusprime, mathieucprime)
+ln = log
+
+__all__ = [
+    'factorial', 'factorial2', 'rf', 'ff', 'binomial', 'RisingFactorial',
+    'FallingFactorial', 'subfactorial',
+
+    'carmichael', 'fibonacci', 'lucas', 'motzkin', 'tribonacci', 'harmonic',
+    'bernoulli', 'bell', 'euler', 'catalan', 'genocchi', 'andre', 'partition',
+    'divisor_sigma', 'udivisor_sigma', 'legendre_symbol', 'jacobi_symbol', 'kronecker_symbol',
+    'mobius', 'primenu', 'primeomega', 'totient', 'reduced_totient', 'primepi',
+
+    'sqrt', 'root', 'Min', 'Max', 'Id', 'real_root', 'cbrt', 'Rem',
+
+    're', 'im', 'sign', 'Abs', 'conjugate', 'arg', 'polar_lift',
+    'periodic_argument', 'unbranched_argument', 'principal_branch',
+    'transpose', 'adjoint', 'polarify', 'unpolarify',
+
+    'sin', 'cos', 'tan', 'sec', 'csc', 'cot', 'sinc', 'asin', 'acos', 'atan',
+    'asec', 'acsc', 'acot', 'atan2',
+
+    'exp_polar', 'exp', 'ln', 'log', 'LambertW',
+
+    'sinh', 'cosh', 'tanh', 'coth', 'sech', 'csch', 'asinh', 'acosh', 'atanh',
+    'acoth', 'asech', 'acsch',
+
+    'floor', 'ceiling', 'frac',
+
+    'Piecewise', 'piecewise_fold', 'piecewise_exclusive',
+
+    'erf', 'erfc', 'erfi', 'erf2', 'erfinv', 'erfcinv', 'erf2inv', 'Ei',
+    'expint', 'E1', 'li', 'Li', 'Si', 'Ci', 'Shi', 'Chi', 'fresnels',
+    'fresnelc',
+
+    'gamma', 'lowergamma', 'uppergamma', 'polygamma', 'loggamma', 'digamma',
+    'trigamma', 'multigamma',
+
+    'dirichlet_eta', 'zeta', 'lerchphi', 'polylog', 'stieltjes', 'riemann_xi',
+
+    'Eijk', 'LeviCivita', 'KroneckerDelta',
+
+    'SingularityFunction',
+
+    'DiracDelta', 'Heaviside',
+
+    'bspline_basis', 'bspline_basis_set', 'interpolating_spline',
+
+    'besselj', 'bessely', 'besseli', 'besselk', 'hankel1', 'hankel2', 'jn',
+    'yn', 'jn_zeros', 'hn1', 'hn2', 'airyai', 'airybi', 'airyaiprime',
+    'airybiprime', 'marcumq',
+
+    'hyper', 'meijerg', 'appellf1',
+
+    'legendre', 'assoc_legendre', 'hermite', 'hermite_prob', 'chebyshevt',
+    'chebyshevu', 'chebyshevu_root', 'chebyshevt_root', 'laguerre',
+    'assoc_laguerre', 'gegenbauer', 'jacobi', 'jacobi_normalized',
+
+    'Ynm', 'Ynm_c', 'Znm',
+
+    'elliptic_k', 'elliptic_f', 'elliptic_e', 'elliptic_pi',
+
+    'beta', 'betainc', 'betainc_regularized',
+
+    'mathieus', 'mathieuc', 'mathieusprime', 'mathieucprime',
+]

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

@@ -0,0 +1,45 @@
+"""
+A geometry module for the SymPy library. This module contains all of the
+entities and functions needed to construct basic geometrical data and to
+perform simple informational queries.
+
+Usage:
+======
+
+Examples
+========
+
+"""
+from sympy.geometry.point import Point, Point2D, Point3D
+from sympy.geometry.line import Line, Ray, Segment, Line2D, Segment2D, Ray2D, \
+    Line3D, Segment3D, Ray3D
+from sympy.geometry.plane import Plane
+from sympy.geometry.ellipse import Ellipse, Circle
+from sympy.geometry.polygon import Polygon, RegularPolygon, Triangle, rad, deg
+from sympy.geometry.util import are_similar, centroid, convex_hull, idiff, \
+    intersection, closest_points, farthest_points
+from sympy.geometry.exceptions import GeometryError
+from sympy.geometry.curve import Curve
+from sympy.geometry.parabola import Parabola
+
+__all__ = [
+    'Point', 'Point2D', 'Point3D',
+
+    'Line', 'Ray', 'Segment', 'Line2D', 'Segment2D', 'Ray2D', 'Line3D',
+    'Segment3D', 'Ray3D',
+
+    'Plane',
+
+    'Ellipse', 'Circle',
+
+    'Polygon', 'RegularPolygon', 'Triangle', 'rad', 'deg',
+
+    'are_similar', 'centroid', 'convex_hull', 'idiff', 'intersection',
+    'closest_points', 'farthest_points',
+
+    'GeometryError',
+
+    'Curve',
+
+    'Parabola',
+]

.venv/lib/python3.13/site-packages/sympy/geometry/curve.py

@@ -0,0 +1,424 @@
+"""Curves in 2-dimensional Euclidean space.
+
+Contains
+========
+Curve
+
+"""
+
+from sympy.functions.elementary.miscellaneous import sqrt
+from sympy.core import diff
+from sympy.core.containers import Tuple
+from sympy.core.symbol import _symbol
+from sympy.geometry.entity import GeometryEntity, GeometrySet
+from sympy.geometry.point import Point
+from sympy.integrals import integrate
+from sympy.matrices import Matrix, rot_axis3
+from sympy.utilities.iterables import is_sequence
+
+from mpmath.libmp.libmpf import prec_to_dps
+
+
+class Curve(GeometrySet):
+    """A curve in space.
+
+    A curve is defined by parametric functions for the coordinates, a
+    parameter and the lower and upper bounds for the parameter value.
+
+    Parameters
+    ==========
+
+    function : list of functions
+    limits : 3-tuple
+        Function parameter and lower and upper bounds.
+
+    Attributes
+    ==========
+
+    functions
+    parameter
+    limits
+
+    Raises
+    ======
+
+    ValueError
+        When `functions` are specified incorrectly.
+        When `limits` are specified incorrectly.
+
+    Examples
+    ========
+
+    >>> from sympy import Curve, sin, cos, interpolate
+    >>> from sympy.abc import t, a
+    >>> C = Curve((sin(t), cos(t)), (t, 0, 2))
+    >>> C.functions
+    (sin(t), cos(t))
+    >>> C.limits
+    (t, 0, 2)
+    >>> C.parameter
+    t
+    >>> C = Curve((t, interpolate([1, 4, 9, 16], t)), (t, 0, 1)); C
+    Curve((t, t**2), (t, 0, 1))
+    >>> C.subs(t, 4)
+    Point2D(4, 16)
+    >>> C.arbitrary_point(a)
+    Point2D(a, a**2)
+
+    See Also
+    ========
+
+    sympy.core.function.Function
+    sympy.polys.polyfuncs.interpolate
+
+    """
+
+    def __new__(cls, function, limits):
+        if not is_sequence(function) or len(function) != 2:
+            raise ValueError("Function argument should be (x(t), y(t)) "
+                "but got %s" % str(function))
+        if not is_sequence(limits) or len(limits) != 3:
+            raise ValueError("Limit argument should be (t, tmin, tmax) "
+                "but got %s" % str(limits))
+
+        return GeometryEntity.__new__(cls, Tuple(*function), Tuple(*limits))
+
+    def __call__(self, f):
+        return self.subs(self.parameter, f)
+
+    def _eval_subs(self, old, new):
+        if old == self.parameter:
+            return Point(*[f.subs(old, new) for f in self.functions])
+
+    def _eval_evalf(self, prec=15, **options):
+        f, (t, a, b) = self.args
+        dps = prec_to_dps(prec)
+        f = tuple([i.evalf(n=dps, **options) for i in f])
+        a, b = [i.evalf(n=dps, **options) for i in (a, b)]
+        return self.func(f, (t, a, b))
+
+    def arbitrary_point(self, parameter='t'):
+        """A parameterized point on the curve.
+
+        Parameters
+        ==========
+
+        parameter : str or Symbol, optional
+            Default value is 't'.
+            The Curve's parameter is selected with None or self.parameter
+            otherwise the provided symbol is used.
+
+        Returns
+        =======
+
+        Point :
+            Returns a point in parametric form.
+
+        Raises
+        ======
+
+        ValueError
+            When `parameter` already appears in the functions.
+
+        Examples
+        ========
+
+        >>> from sympy import Curve, Symbol
+        >>> from sympy.abc import s
+        >>> C = Curve([2*s, s**2], (s, 0, 2))
+        >>> C.arbitrary_point()
+        Point2D(2*t, t**2)
+        >>> C.arbitrary_point(C.parameter)
+        Point2D(2*s, s**2)
+        >>> C.arbitrary_point(None)
+        Point2D(2*s, s**2)
+        >>> C.arbitrary_point(Symbol('a'))
+        Point2D(2*a, a**2)
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point
+
+        """
+        if parameter is None:
+            return Point(*self.functions)
+
+        tnew = _symbol(parameter, self.parameter, real=True)
+        t = self.parameter
+        if (tnew.name != t.name and
+                tnew.name in (f.name for f in self.free_symbols)):
+            raise ValueError('Symbol %s already appears in object '
+                'and cannot be used as a parameter.' % tnew.name)
+        return Point(*[w.subs(t, tnew) for w in self.functions])
+
+    @property
+    def free_symbols(self):
+        """Return a set of symbols other than the bound symbols used to
+        parametrically define the Curve.
+
+        Returns
+        =======
+
+        set :
+            Set of all non-parameterized symbols.
+
+        Examples
+        ========
+
+        >>> from sympy.abc import t, a
+        >>> from sympy import Curve
+        >>> Curve((t, t**2), (t, 0, 2)).free_symbols
+        set()
+        >>> Curve((t, t**2), (t, a, 2)).free_symbols
+        {a}
+
+        """
+        free = set()
+        for a in self.functions + self.limits[1:]:
+            free |= a.free_symbols
+        free = free.difference({self.parameter})
+        return free
+
+    @property
+    def ambient_dimension(self):
+        """The dimension of the curve.
+
+        Returns
+        =======
+
+        int :
+            the dimension of curve.
+
+        Examples
+        ========
+
+        >>> from sympy.abc import t
+        >>> from sympy import Curve
+        >>> C = Curve((t, t**2), (t, 0, 2))
+        >>> C.ambient_dimension
+        2
+
+        """
+
+        return len(self.args[0])
+
+    @property
+    def functions(self):
+        """The functions specifying the curve.
+
+        Returns
+        =======
+
+        functions :
+            list of parameterized coordinate functions.
+
+        Examples
+        ========
+
+        >>> from sympy.abc import t
+        >>> from sympy import Curve
+        >>> C = Curve((t, t**2), (t, 0, 2))
+        >>> C.functions
+        (t, t**2)
+
+        See Also
+        ========
+
+        parameter
+
+        """
+        return self.args[0]
+
+    @property
+    def limits(self):
+        """The limits for the curve.
+
+        Returns
+        =======
+
+        limits : tuple
+            Contains parameter and lower and upper limits.
+
+        Examples
+        ========
+
+        >>> from sympy.abc import t
+        >>> from sympy import Curve
+        >>> C = Curve([t, t**3], (t, -2, 2))
+        >>> C.limits
+        (t, -2, 2)
+
+        See Also
+        ========
+
+        plot_interval
+
+        """
+        return self.args[1]
+
+    @property
+    def parameter(self):
+        """The curve function variable.
+
+        Returns
+        =======
+
+        Symbol :
+            returns a bound symbol.
+
+        Examples
+        ========
+
+        >>> from sympy.abc import t
+        >>> from sympy import Curve
+        >>> C = Curve([t, t**2], (t, 0, 2))
+        >>> C.parameter
+        t
+
+        See Also
+        ========
+
+        functions
+
+        """
+        return self.args[1][0]
+
+    @property
+    def length(self):
+        """The curve length.
+
+        Examples
+        ========
+
+        >>> from sympy import Curve
+        >>> from sympy.abc import t
+        >>> Curve((t, t), (t, 0, 1)).length
+        sqrt(2)
+
+        """
+        integrand = sqrt(sum(diff(func, self.limits[0])**2 for func in self.functions))
+        return integrate(integrand, self.limits)
+
+    def plot_interval(self, parameter='t'):
+        """The plot interval for the default geometric plot of the curve.
+
+        Parameters
+        ==========
+
+        parameter : str or Symbol, optional
+            Default value is 't';
+            otherwise the provided symbol is used.
+
+        Returns
+        =======
+
+        List :
+            the plot interval as below:
+                [parameter, lower_bound, upper_bound]
+
+        Examples
+        ========
+
+        >>> from sympy import Curve, sin
+        >>> from sympy.abc import x, s
+        >>> Curve((x, sin(x)), (x, 1, 2)).plot_interval()
+        [t, 1, 2]
+        >>> Curve((x, sin(x)), (x, 1, 2)).plot_interval(s)
+        [s, 1, 2]
+
+        See Also
+        ========
+
+        limits : Returns limits of the parameter interval
+
+        """
+        t = _symbol(parameter, self.parameter, real=True)
+        return [t] + list(self.limits[1:])
+
+    def rotate(self, angle=0, pt=None):
+        """This function is used to rotate a curve along given point ``pt`` at given angle(in radian).
+
+        Parameters
+        ==========
+
+        angle :
+            the angle at which the curve will be rotated(in radian) in counterclockwise direction.
+            default value of angle is 0.
+
+        pt : Point
+            the point along which the curve will be rotated.
+            If no point given, the curve will be rotated around origin.
+
+        Returns
+        =======
+
+        Curve :
+            returns a curve rotated at given angle along given point.
+
+        Examples
+        ========
+
+        >>> from sympy import Curve, pi
+        >>> from sympy.abc import x
+        >>> Curve((x, x), (x, 0, 1)).rotate(pi/2)
+        Curve((-x, x), (x, 0, 1))
+
+        """
+        if pt:
+            pt = -Point(pt, dim=2)
+        else:
+            pt = Point(0,0)
+        rv = self.translate(*pt.args)
+        f = list(rv.functions)
+        f.append(0)
+        f = Matrix(1, 3, f)
+        f *= rot_axis3(angle)
+        rv = self.func(f[0, :2].tolist()[0], self.limits)
+        pt = -pt
+        return rv.translate(*pt.args)
+
+    def scale(self, x=1, y=1, pt=None):
+        """Override GeometryEntity.scale since Curve is not made up of Points.
+
+        Returns
+        =======
+
+        Curve :
+            returns scaled curve.
+
+        Examples
+        ========
+
+        >>> from sympy import Curve
+        >>> from sympy.abc import x
+        >>> Curve((x, x), (x, 0, 1)).scale(2)
+        Curve((2*x, x), (x, 0, 1))
+
+        """
+        if pt:
+            pt = Point(pt, dim=2)
+            return self.translate(*(-pt).args).scale(x, y).translate(*pt.args)
+        fx, fy = self.functions
+        return self.func((fx*x, fy*y), self.limits)
+
+    def translate(self, x=0, y=0):
+        """Translate the Curve by (x, y).
+
+        Returns
+        =======
+
+        Curve :
+            returns a translated curve.
+
+        Examples
+        ========
+
+        >>> from sympy import Curve
+        >>> from sympy.abc import x
+        >>> Curve((x, x), (x, 0, 1)).translate(1, 2)
+        Curve((x + 1, x + 2), (x, 0, 1))
+
+        """
+        fx, fy = self.functions
+        return self.func((fx + x, fy + y), self.limits)

.venv/lib/python3.13/site-packages/sympy/geometry/ellipse.py

@@ -0,0 +1,1768 @@
+"""Elliptical geometrical entities.
+
+Contains
+* Ellipse
+* Circle
+
+"""
+
+from sympy.core.expr import Expr
+from sympy.core.relational import Eq
+from sympy.core import S, pi, sympify
+from sympy.core.evalf import N
+from sympy.core.parameters import global_parameters
+from sympy.core.logic import fuzzy_bool
+from sympy.core.numbers import Rational, oo
+from sympy.core.sorting import ordered
+from sympy.core.symbol import Dummy, uniquely_named_symbol, _symbol
+from sympy.simplify.simplify import simplify
+from sympy.simplify.trigsimp import trigsimp
+from sympy.functions.elementary.miscellaneous import sqrt, Max
+from sympy.functions.elementary.trigonometric import cos, sin
+from sympy.functions.special.elliptic_integrals import elliptic_e
+from .entity import GeometryEntity, GeometrySet
+from .exceptions import GeometryError
+from .line import Line, Segment, Ray2D, Segment2D, Line2D, LinearEntity3D
+from .point import Point, Point2D, Point3D
+from .util import idiff, find
+from sympy.polys import DomainError, Poly, PolynomialError
+from sympy.polys.polyutils import _not_a_coeff, _nsort
+from sympy.solvers import solve
+from sympy.solvers.solveset import linear_coeffs
+from sympy.utilities.misc import filldedent, func_name
+
+from mpmath.libmp.libmpf import prec_to_dps
+
+import random
+
+x, y = [Dummy('ellipse_dummy', real=True) for i in range(2)]
+
+
+class Ellipse(GeometrySet):
+    """An elliptical GeometryEntity.
+
+    Parameters
+    ==========
+
+    center : Point, optional
+        Default value is Point(0, 0)
+    hradius : number or SymPy expression, optional
+    vradius : number or SymPy expression, optional
+    eccentricity : number or SymPy expression, optional
+        Two of `hradius`, `vradius` and `eccentricity` must be supplied to
+        create an Ellipse. The third is derived from the two supplied.
+
+    Attributes
+    ==========
+
+    center
+    hradius
+    vradius
+    area
+    circumference
+    eccentricity
+    periapsis
+    apoapsis
+    focus_distance
+    foci
+
+    Raises
+    ======
+
+    GeometryError
+        When `hradius`, `vradius` and `eccentricity` are incorrectly supplied
+        as parameters.
+    TypeError
+        When `center` is not a Point.
+
+    See Also
+    ========
+
+    Circle
+
+    Notes
+    -----
+    Constructed from a center and two radii, the first being the horizontal
+    radius (along the x-axis) and the second being the vertical radius (along
+    the y-axis).
+
+    When symbolic value for hradius and vradius are used, any calculation that
+    refers to the foci or the major or minor axis will assume that the ellipse
+    has its major radius on the x-axis. If this is not true then a manual
+    rotation is necessary.
+
+    Examples
+    ========
+
+    >>> from sympy import Ellipse, Point, Rational
+    >>> e1 = Ellipse(Point(0, 0), 5, 1)
+    >>> e1.hradius, e1.vradius
+    (5, 1)
+    >>> e2 = Ellipse(Point(3, 1), hradius=3, eccentricity=Rational(4, 5))
+    >>> e2
+    Ellipse(Point2D(3, 1), 3, 9/5)
+
+    """
+
+    def __contains__(self, o):
+        if isinstance(o, Point):
+            res = self.equation(x, y).subs({x: o.x, y: o.y})
+            return trigsimp(simplify(res)) is S.Zero
+        elif isinstance(o, Ellipse):
+            return self == o
+        return False
+
+    def __eq__(self, o):
+        """Is the other GeometryEntity the same as this ellipse?"""
+        return isinstance(o, Ellipse) and (self.center == o.center and
+                                           self.hradius == o.hradius and
+                                           self.vradius == o.vradius)
+
+    def __hash__(self):
+        return super().__hash__()
+
+    def __new__(
+        cls, center=None, hradius=None, vradius=None, eccentricity=None, **kwargs):
+
+        hradius = sympify(hradius)
+        vradius = sympify(vradius)
+
+        if center is None:
+            center = Point(0, 0)
+        else:
+            if len(center) != 2:
+                raise ValueError('The center of "{}" must be a two dimensional point'.format(cls))
+            center = Point(center, dim=2)
+
+        if len(list(filter(lambda x: x is not None, (hradius, vradius, eccentricity)))) != 2:
+            raise ValueError(filldedent('''
+                Exactly two arguments of "hradius", "vradius", and
+                "eccentricity" must not be None.'''))
+
+        if eccentricity is not None:
+            eccentricity = sympify(eccentricity)
+            if eccentricity.is_negative:
+                raise GeometryError("Eccentricity of ellipse/circle should lie between [0, 1)")
+            elif hradius is None:
+                hradius = vradius / sqrt(1 - eccentricity**2)
+            elif vradius is None:
+                vradius = hradius * sqrt(1 - eccentricity**2)
+
+        if hradius == vradius:
+            return Circle(center, hradius, **kwargs)
+
+        if S.Zero in (hradius, vradius):
+            return Segment(Point(center[0] - hradius, center[1] - vradius), Point(center[0] + hradius, center[1] + vradius))
+
+        if hradius.is_real is False or vradius.is_real is False:
+            raise GeometryError("Invalid value encountered when computing hradius / vradius.")
+
+        return GeometryEntity.__new__(cls, center, hradius, vradius, **kwargs)
+
+    def _svg(self, scale_factor=1., fill_color="#66cc99"):
+        """Returns SVG ellipse element for the Ellipse.
+
+        Parameters
+        ==========
+
+        scale_factor : float
+            Multiplication factor for the SVG stroke-width.  Default is 1.
+        fill_color : str, optional
+            Hex string for fill color. Default is "#66cc99".
+        """
+
+        c = N(self.center)
+        h, v = N(self.hradius), N(self.vradius)
+        return (
+            '<ellipse fill="{1}" stroke="#555555" '
+            'stroke-width="{0}" opacity="0.6" cx="{2}" cy="{3}" rx="{4}" ry="{5}"/>'
+        ).format(2. * scale_factor, fill_color, c.x, c.y, h, v)
+
+    @property
+    def ambient_dimension(self):
+        return 2
+
+    @property
+    def apoapsis(self):
+        """The apoapsis of the ellipse.
+
+        The greatest distance between the focus and the contour.
+
+        Returns
+        =======
+
+        apoapsis : number
+
+        See Also
+        ========
+
+        periapsis : Returns shortest distance between foci and contour
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> p1 = Point(0, 0)
+        >>> e1 = Ellipse(p1, 3, 1)
+        >>> e1.apoapsis
+        2*sqrt(2) + 3
+
+        """
+        return self.major * (1 + self.eccentricity)
+
+    def arbitrary_point(self, parameter='t'):
+        """A parameterized point on the ellipse.
+
+        Parameters
+        ==========
+
+        parameter : str, optional
+            Default value is 't'.
+
+        Returns
+        =======
+
+        arbitrary_point : Point
+
+        Raises
+        ======
+
+        ValueError
+            When `parameter` already appears in the functions.
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> e1 = Ellipse(Point(0, 0), 3, 2)
+        >>> e1.arbitrary_point()
+        Point2D(3*cos(t), 2*sin(t))
+
+        """
+        t = _symbol(parameter, real=True)
+        if t.name in (f.name for f in self.free_symbols):
+            raise ValueError(filldedent('Symbol %s already appears in object '
+                                        'and cannot be used as a parameter.' % t.name))
+        return Point(self.center.x + self.hradius*cos(t),
+                     self.center.y + self.vradius*sin(t))
+
+    @property
+    def area(self):
+        """The area of the ellipse.
+
+        Returns
+        =======
+
+        area : number
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> p1 = Point(0, 0)
+        >>> e1 = Ellipse(p1, 3, 1)
+        >>> e1.area
+        3*pi
+
+        """
+        return simplify(S.Pi * self.hradius * self.vradius)
+
+    @property
+    def bounds(self):
+        """Return a tuple (xmin, ymin, xmax, ymax) representing the bounding
+        rectangle for the geometric figure.
+
+        """
+
+        h, v = self.hradius, self.vradius
+        return (self.center.x - h, self.center.y - v, self.center.x + h, self.center.y + v)
+
+    @property
+    def center(self):
+        """The center of the ellipse.
+
+        Returns
+        =======
+
+        center : number
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> p1 = Point(0, 0)
+        >>> e1 = Ellipse(p1, 3, 1)
+        >>> e1.center
+        Point2D(0, 0)
+
+        """
+        return self.args[0]
+
+    @property
+    def circumference(self):
+        """The circumference of the ellipse.
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> p1 = Point(0, 0)
+        >>> e1 = Ellipse(p1, 3, 1)
+        >>> e1.circumference
+        12*elliptic_e(8/9)
+
+        """
+        if self.eccentricity == 1:
+            # degenerate
+            return 4*self.major
+        elif self.eccentricity == 0:
+            # circle
+            return 2*pi*self.hradius
+        else:
+            return 4*self.major*elliptic_e(self.eccentricity**2)
+
+    @property
+    def eccentricity(self):
+        """The eccentricity of the ellipse.
+
+        Returns
+        =======
+
+        eccentricity : number
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse, sqrt
+        >>> p1 = Point(0, 0)
+        >>> e1 = Ellipse(p1, 3, sqrt(2))
+        >>> e1.eccentricity
+        sqrt(7)/3
+
+        """
+        return self.focus_distance / self.major
+
+    def encloses_point(self, p):
+        """
+        Return True if p is enclosed by (is inside of) self.
+
+        Notes
+        -----
+        Being on the border of self is considered False.
+
+        Parameters
+        ==========
+
+        p : Point
+
+        Returns
+        =======
+
+        encloses_point : True, False or None
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point
+
+        Examples
+        ========
+
+        >>> from sympy import Ellipse, S
+        >>> from sympy.abc import t
+        >>> e = Ellipse((0, 0), 3, 2)
+        >>> e.encloses_point((0, 0))
+        True
+        >>> e.encloses_point(e.arbitrary_point(t).subs(t, S.Half))
+        False
+        >>> e.encloses_point((4, 0))
+        False
+
+        """
+        p = Point(p, dim=2)
+        if p in self:
+            return False
+
+        if len(self.foci) == 2:
+            # if the combined distance from the foci to p (h1 + h2) is less
+            # than the combined distance from the foci to the minor axis
+            # (which is the same as the major axis length) then p is inside
+            # the ellipse
+            h1, h2 = [f.distance(p) for f in self.foci]
+            test = 2*self.major - (h1 + h2)
+        else:
+            test = self.radius - self.center.distance(p)
+
+        return fuzzy_bool(test.is_positive)
+
+    def equation(self, x='x', y='y', _slope=None):
+        """
+        Returns the equation of an ellipse aligned with the x and y axes;
+        when slope is given, the equation returned corresponds to an ellipse
+        with a major axis having that slope.
+
+        Parameters
+        ==========
+
+        x : str, optional
+            Label for the x-axis. Default value is 'x'.
+        y : str, optional
+            Label for the y-axis. Default value is 'y'.
+        _slope : Expr, optional
+                The slope of the major axis. Ignored when 'None'.
+
+        Returns
+        =======
+
+        equation : SymPy expression
+
+        See Also
+        ========
+
+        arbitrary_point : Returns parameterized point on ellipse
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse, pi
+        >>> from sympy.abc import x, y
+        >>> e1 = Ellipse(Point(1, 0), 3, 2)
+        >>> eq1 = e1.equation(x, y); eq1
+        y**2/4 + (x/3 - 1/3)**2 - 1
+        >>> eq2 = e1.equation(x, y, _slope=1); eq2
+        (-x + y + 1)**2/8 + (x + y - 1)**2/18 - 1
+
+        A point on e1 satisfies eq1. Let's use one on the x-axis:
+
+        >>> p1 = e1.center + Point(e1.major, 0)
+        >>> assert eq1.subs(x, p1.x).subs(y, p1.y) == 0
+
+        When rotated the same as the rotated ellipse, about the center
+        point of the ellipse, it will satisfy the rotated ellipse's
+        equation, too:
+
+        >>> r1 = p1.rotate(pi/4, e1.center)
+        >>> assert eq2.subs(x, r1.x).subs(y, r1.y) == 0
+
+        References
+        ==========
+
+        .. [1] https://math.stackexchange.com/questions/108270/what-is-the-equation-of-an-ellipse-that-is-not-aligned-with-the-axis
+        .. [2] https://en.wikipedia.org/wiki/Ellipse#Shifted_ellipse
+
+        """
+
+        x = _symbol(x, real=True)
+        y = _symbol(y, real=True)
+
+        dx = x - self.center.x
+        dy = y - self.center.y
+
+        if _slope is not None:
+            L = (dy - _slope*dx)**2
+            l = (_slope*dy + dx)**2
+            h = 1 + _slope**2
+            b = h*self.major**2
+            a = h*self.minor**2
+            return l/b + L/a - 1
+
+        else:
+            t1 = (dx/self.hradius)**2
+            t2 = (dy/self.vradius)**2
+            return t1 + t2 - 1
+
+    def evolute(self, x='x', y='y'):
+        """The equation of evolute of the ellipse.
+
+        Parameters
+        ==========
+
+        x : str, optional
+            Label for the x-axis. Default value is 'x'.
+        y : str, optional
+            Label for the y-axis. Default value is 'y'.
+
+        Returns
+        =======
+
+        equation : SymPy expression
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> e1 = Ellipse(Point(1, 0), 3, 2)
+        >>> e1.evolute()
+        2**(2/3)*y**(2/3) + (3*x - 3)**(2/3) - 5**(2/3)
+        """
+        if len(self.args) != 3:
+            raise NotImplementedError('Evolute of arbitrary Ellipse is not supported.')
+        x = _symbol(x, real=True)
+        y = _symbol(y, real=True)
+        t1 = (self.hradius*(x - self.center.x))**Rational(2, 3)
+        t2 = (self.vradius*(y - self.center.y))**Rational(2, 3)
+        return t1 + t2 - (self.hradius**2 - self.vradius**2)**Rational(2, 3)
+
+    @property
+    def foci(self):
+        """The foci of the ellipse.
+
+        Notes
+        -----
+        The foci can only be calculated if the major/minor axes are known.
+
+        Raises
+        ======
+
+        ValueError
+            When the major and minor axis cannot be determined.
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point
+        focus_distance : Returns the distance between focus and center
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> p1 = Point(0, 0)
+        >>> e1 = Ellipse(p1, 3, 1)
+        >>> e1.foci
+        (Point2D(-2*sqrt(2), 0), Point2D(2*sqrt(2), 0))
+
+        """
+        c = self.center
+        hr, vr = self.hradius, self.vradius
+        if hr == vr:
+            return (c, c)
+
+        # calculate focus distance manually, since focus_distance calls this
+        # routine
+        fd = sqrt(self.major**2 - self.minor**2)
+        if hr == self.minor:
+            # foci on the y-axis
+            return (c + Point(0, -fd), c + Point(0, fd))
+        elif hr == self.major:
+            # foci on the x-axis
+            return (c + Point(-fd, 0), c + Point(fd, 0))
+
+    @property
+    def focus_distance(self):
+        """The focal distance of the ellipse.
+
+        The distance between the center and one focus.
+
+        Returns
+        =======
+
+        focus_distance : number
+
+        See Also
+        ========
+
+        foci
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> p1 = Point(0, 0)
+        >>> e1 = Ellipse(p1, 3, 1)
+        >>> e1.focus_distance
+        2*sqrt(2)
+
+        """
+        return Point.distance(self.center, self.foci[0])
+
+    @property
+    def hradius(self):
+        """The horizontal radius of the ellipse.
+
+        Returns
+        =======
+
+        hradius : number
+
+        See Also
+        ========
+
+        vradius, major, minor
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> p1 = Point(0, 0)
+        >>> e1 = Ellipse(p1, 3, 1)
+        >>> e1.hradius
+        3
+
+        """
+        return self.args[1]
+
+    def intersection(self, o):
+        """The intersection of this ellipse and another geometrical entity
+        `o`.
+
+        Parameters
+        ==========
+
+        o : GeometryEntity
+
+        Returns
+        =======
+
+        intersection : list of GeometryEntity objects
+
+        Notes
+        -----
+        Currently supports intersections with Point, Line, Segment, Ray,
+        Circle and Ellipse types.
+
+        See Also
+        ========
+
+        sympy.geometry.entity.GeometryEntity
+
+        Examples
+        ========
+
+        >>> from sympy import Ellipse, Point, Line
+        >>> e = Ellipse(Point(0, 0), 5, 7)
+        >>> e.intersection(Point(0, 0))
+        []
+        >>> e.intersection(Point(5, 0))
+        [Point2D(5, 0)]
+        >>> e.intersection(Line(Point(0,0), Point(0, 1)))
+        [Point2D(0, -7), Point2D(0, 7)]
+        >>> e.intersection(Line(Point(5,0), Point(5, 1)))
+        [Point2D(5, 0)]
+        >>> e.intersection(Line(Point(6,0), Point(6, 1)))
+        []
+        >>> e = Ellipse(Point(-1, 0), 4, 3)
+        >>> e.intersection(Ellipse(Point(1, 0), 4, 3))
+        [Point2D(0, -3*sqrt(15)/4), Point2D(0, 3*sqrt(15)/4)]
+        >>> e.intersection(Ellipse(Point(5, 0), 4, 3))
+        [Point2D(2, -3*sqrt(7)/4), Point2D(2, 3*sqrt(7)/4)]
+        >>> e.intersection(Ellipse(Point(100500, 0), 4, 3))
+        []
+        >>> e.intersection(Ellipse(Point(0, 0), 3, 4))
+        [Point2D(3, 0), Point2D(-363/175, -48*sqrt(111)/175), Point2D(-363/175, 48*sqrt(111)/175)]
+        >>> e.intersection(Ellipse(Point(-1, 0), 3, 4))
+        [Point2D(-17/5, -12/5), Point2D(-17/5, 12/5), Point2D(7/5, -12/5), Point2D(7/5, 12/5)]
+        """
+        # TODO: Replace solve with nonlinsolve, when nonlinsolve will be able to solve in real domain
+
+        if isinstance(o, Point):
+            if o in self:
+                return [o]
+            else:
+                return []
+
+        elif isinstance(o, (Segment2D, Ray2D)):
+            ellipse_equation = self.equation(x, y)
+            result = solve([ellipse_equation, Line(
+                o.points[0], o.points[1]).equation(x, y)], [x, y],
+                set=True)[1]
+            return list(ordered([Point(i) for i in result if i in o]))
+
+        elif isinstance(o, Polygon):
+            return o.intersection(self)
+
+        elif isinstance(o, (Ellipse, Line2D)):
+            if o == self:
+                return self
+            else:
+                ellipse_equation = self.equation(x, y)
+                return list(ordered([Point(i) for i in solve(
+                    [ellipse_equation, o.equation(x, y)], [x, y],
+                    set=True)[1]]))
+        elif isinstance(o, LinearEntity3D):
+            raise TypeError('Entity must be two dimensional, not three dimensional')
+        else:
+            raise TypeError('Intersection not handled for %s' % func_name(o))
+
+    def is_tangent(self, o):
+        """Is `o` tangent to the ellipse?
+
+        Parameters
+        ==========
+
+        o : GeometryEntity
+            An Ellipse, LinearEntity or Polygon
+
+        Raises
+        ======
+
+        NotImplementedError
+            When the wrong type of argument is supplied.
+
+        Returns
+        =======
+
+        is_tangent: boolean
+            True if o is tangent to the ellipse, False otherwise.
+
+        See Also
+        ========
+
+        tangent_lines
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse, Line
+        >>> p0, p1, p2 = Point(0, 0), Point(3, 0), Point(3, 3)
+        >>> e1 = Ellipse(p0, 3, 2)
+        >>> l1 = Line(p1, p2)
+        >>> e1.is_tangent(l1)
+        True
+
+        """
+        if isinstance(o, Point2D):
+            return False
+        elif isinstance(o, Ellipse):
+            intersect = self.intersection(o)
+            if isinstance(intersect, Ellipse):
+                return True
+            elif intersect:
+                return all((self.tangent_lines(i)[0]).equals(o.tangent_lines(i)[0]) for i in intersect)
+            else:
+                return False
+        elif isinstance(o, Line2D):
+            hit = self.intersection(o)
+            if not hit:
+                return False
+            if len(hit) == 1:
+                return True
+            # might return None if it can't decide
+            return hit[0].equals(hit[1])
+        elif isinstance(o, (Segment2D, Ray2D)):
+            intersect = self.intersection(o)
+            if len(intersect) == 1:
+                return o in self.tangent_lines(intersect[0])[0]
+            else:
+                return False
+        elif isinstance(o, Polygon):
+            return all(self.is_tangent(s) for s in o.sides)
+        elif isinstance(o, (LinearEntity3D, Point3D)):
+            raise TypeError('Entity must be two dimensional, not three dimensional')
+        else:
+            raise TypeError('Is_tangent not handled for %s' % func_name(o))
+
+    @property
+    def major(self):
+        """Longer axis of the ellipse (if it can be determined) else hradius.
+
+        Returns
+        =======
+
+        major : number or expression
+
+        See Also
+        ========
+
+        hradius, vradius, minor
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse, Symbol
+        >>> p1 = Point(0, 0)
+        >>> e1 = Ellipse(p1, 3, 1)
+        >>> e1.major
+        3
+
+        >>> a = Symbol('a')
+        >>> b = Symbol('b')
+        >>> Ellipse(p1, a, b).major
+        a
+        >>> Ellipse(p1, b, a).major
+        b
+
+        >>> m = Symbol('m')
+        >>> M = m + 1
+        >>> Ellipse(p1, m, M).major
+        m + 1
+
+        """
+        ab = self.args[1:3]
+        if len(ab) == 1:
+            return ab[0]
+        a, b = ab
+        o = b - a < 0
+        if o == True:
+            return a
+        elif o == False:
+            return b
+        return self.hradius
+
+    @property
+    def minor(self):
+        """Shorter axis of the ellipse (if it can be determined) else vradius.
+
+        Returns
+        =======
+
+        minor : number or expression
+
+        See Also
+        ========
+
+        hradius, vradius, major
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse, Symbol
+        >>> p1 = Point(0, 0)
+        >>> e1 = Ellipse(p1, 3, 1)
+        >>> e1.minor
+        1
+
+        >>> a = Symbol('a')
+        >>> b = Symbol('b')
+        >>> Ellipse(p1, a, b).minor
+        b
+        >>> Ellipse(p1, b, a).minor
+        a
+
+        >>> m = Symbol('m')
+        >>> M = m + 1
+        >>> Ellipse(p1, m, M).minor
+        m
+
+        """
+        ab = self.args[1:3]
+        if len(ab) == 1:
+            return ab[0]
+        a, b = ab
+        o = a - b < 0
+        if o == True:
+            return a
+        elif o == False:
+            return b
+        return self.vradius
+
+    def normal_lines(self, p, prec=None):
+        """Normal lines between `p` and the ellipse.
+
+        Parameters
+        ==========
+
+        p : Point
+
+        Returns
+        =======
+
+        normal_lines : list with 1, 2 or 4 Lines
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> e = Ellipse((0, 0), 2, 3)
+        >>> c = e.center
+        >>> e.normal_lines(c + Point(1, 0))
+        [Line2D(Point2D(0, 0), Point2D(1, 0))]
+        >>> e.normal_lines(c)
+        [Line2D(Point2D(0, 0), Point2D(0, 1)), Line2D(Point2D(0, 0), Point2D(1, 0))]
+
+        Off-axis points require the solution of a quartic equation. This
+        often leads to very large expressions that may be of little practical
+        use. An approximate solution of `prec` digits can be obtained by
+        passing in the desired value:
+
+        >>> e.normal_lines((3, 3), prec=2)
+        [Line2D(Point2D(-0.81, -2.7), Point2D(0.19, -1.2)),
+        Line2D(Point2D(1.5, -2.0), Point2D(2.5, -2.7))]
+
+        Whereas the above solution has an operation count of 12, the exact
+        solution has an operation count of 2020.
+        """
+        p = Point(p, dim=2)
+
+        # XXX change True to something like self.angle == 0 if the arbitrarily
+        # rotated ellipse is introduced.
+        # https://github.com/sympy/sympy/issues/2815)
+        if True:
+            rv = []
+            if p.x == self.center.x:
+                rv.append(Line(self.center, slope=oo))
+            if p.y == self.center.y:
+                rv.append(Line(self.center, slope=0))
+            if rv:
+                # at these special orientations of p either 1 or 2 normals
+                # exist and we are done
+                return rv
+
+        # find the 4 normal points and construct lines through them with
+        # the corresponding slope
+        eq = self.equation(x, y)
+        dydx = idiff(eq, y, x)
+        norm = -1/dydx
+        slope = Line(p, (x, y)).slope
+        seq = slope - norm
+
+        # TODO: Replace solve with solveset, when this line is tested
+        yis = solve(seq, y)[0]
+        xeq = eq.subs(y, yis).as_numer_denom()[0].expand()
+        if len(xeq.free_symbols) == 1:
+            try:
+                # this is so much faster, it's worth a try
+                xsol = Poly(xeq, x).real_roots()
+            except (DomainError, PolynomialError, NotImplementedError):
+                # TODO: Replace solve with solveset, when these lines are tested
+                xsol = _nsort(solve(xeq, x), separated=True)[0]
+            points = [Point(i, solve(eq.subs(x, i), y)[0]) for i in xsol]
+        else:
+            raise NotImplementedError(
+                'intersections for the general ellipse are not supported')
+        slopes = [norm.subs(zip((x, y), pt.args)) for pt in points]
+        if prec is not None:
+            points = [pt.n(prec) for pt in points]
+            slopes = [i if _not_a_coeff(i) else i.n(prec) for i in slopes]
+        return [Line(pt, slope=s) for pt, s in zip(points, slopes)]
+
+    @property
+    def periapsis(self):
+        """The periapsis of the ellipse.
+
+        The shortest distance between the focus and the contour.
+
+        Returns
+        =======
+
+        periapsis : number
+
+        See Also
+        ========
+
+        apoapsis : Returns greatest distance between focus and contour
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> p1 = Point(0, 0)
+        >>> e1 = Ellipse(p1, 3, 1)
+        >>> e1.periapsis
+        3 - 2*sqrt(2)
+
+        """
+        return self.major * (1 - self.eccentricity)
+
+    @property
+    def semilatus_rectum(self):
+        """
+        Calculates the semi-latus rectum of the Ellipse.
+
+        Semi-latus rectum is defined as one half of the chord through a
+        focus parallel to the conic section directrix of a conic section.
+
+        Returns
+        =======
+
+        semilatus_rectum : number
+
+        See Also
+        ========
+
+        apoapsis : Returns greatest distance between focus and contour
+
+        periapsis : The shortest distance between the focus and the contour
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> p1 = Point(0, 0)
+        >>> e1 = Ellipse(p1, 3, 1)
+        >>> e1.semilatus_rectum
+        1/3
+
+        References
+        ==========
+
+        .. [1] https://mathworld.wolfram.com/SemilatusRectum.html
+        .. [2] https://en.wikipedia.org/wiki/Ellipse#Semi-latus_rectum
+
+        """
+        return self.major * (1 - self.eccentricity ** 2)
+
+    def auxiliary_circle(self):
+        """Returns a Circle whose diameter is the major axis of the ellipse.
+
+        Examples
+        ========
+
+        >>> from sympy import Ellipse, Point, symbols
+        >>> c = Point(1, 2)
+        >>> Ellipse(c, 8, 7).auxiliary_circle()
+        Circle(Point2D(1, 2), 8)
+        >>> a, b = symbols('a b')
+        >>> Ellipse(c, a, b).auxiliary_circle()
+        Circle(Point2D(1, 2), Max(a, b))
+        """
+        return Circle(self.center, Max(self.hradius, self.vradius))
+
+    def director_circle(self):
+        """
+        Returns a Circle consisting of all points where two perpendicular
+        tangent lines to the ellipse cross each other.
+
+        Returns
+        =======
+
+        Circle
+            A director circle returned as a geometric object.
+
+        Examples
+        ========
+
+        >>> from sympy import Ellipse, Point, symbols
+        >>> c = Point(3,8)
+        >>> Ellipse(c, 7, 9).director_circle()
+        Circle(Point2D(3, 8), sqrt(130))
+        >>> a, b = symbols('a b')
+        >>> Ellipse(c, a, b).director_circle()
+        Circle(Point2D(3, 8), sqrt(a**2 + b**2))
+
+        References
+        ==========
+
+        .. [1] https://en.wikipedia.org/wiki/Director_circle
+
+        """
+        return Circle(self.center, sqrt(self.hradius**2 + self.vradius**2))
+
+    def plot_interval(self, parameter='t'):
+        """The plot interval for the default geometric plot of the Ellipse.
+
+        Parameters
+        ==========
+
+        parameter : str, optional
+            Default value is 't'.
+
+        Returns
+        =======
+
+        plot_interval : list
+            [parameter, lower_bound, upper_bound]
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> e1 = Ellipse(Point(0, 0), 3, 2)
+        >>> e1.plot_interval()
+        [t, -pi, pi]
+
+        """
+        t = _symbol(parameter, real=True)
+        return [t, -S.Pi, S.Pi]
+
+    def random_point(self, seed=None):
+        """A random point on the ellipse.
+
+        Returns
+        =======
+
+        point : Point
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> e1 = Ellipse(Point(0, 0), 3, 2)
+        >>> e1.random_point() # gives some random point
+        Point2D(...)
+        >>> p1 = e1.random_point(seed=0); p1.n(2)
+        Point2D(2.1, 1.4)
+
+        Notes
+        =====
+
+        When creating a random point, one may simply replace the
+        parameter with a random number. When doing so, however, the
+        random number should be made a Rational or else the point
+        may not test as being in the ellipse:
+
+        >>> from sympy.abc import t
+        >>> from sympy import Rational
+        >>> arb = e1.arbitrary_point(t); arb
+        Point2D(3*cos(t), 2*sin(t))
+        >>> arb.subs(t, .1) in e1
+        False
+        >>> arb.subs(t, Rational(.1)) in e1
+        True
+        >>> arb.subs(t, Rational('.1')) in e1
+        True
+
+        See Also
+        ========
+        sympy.geometry.point.Point
+        arbitrary_point : Returns parameterized point on ellipse
+        """
+        t = _symbol('t', real=True)
+        x, y = self.arbitrary_point(t).args
+        # get a random value in [-1, 1) corresponding to cos(t)
+        # and confirm that it will test as being in the ellipse
+        if seed is not None:
+            rng = random.Random(seed)
+        else:
+            rng = random
+        # simplify this now or else the Float will turn s into a Float
+        r = Rational(rng.random())
+        c = 2*r - 1
+        s = sqrt(1 - c**2)
+        return Point(x.subs(cos(t), c), y.subs(sin(t), s))
+
+    def reflect(self, line):
+        """Override GeometryEntity.reflect since the radius
+        is not a GeometryEntity.
+
+        Examples
+        ========
+
+        >>> from sympy import Circle, Line
+        >>> Circle((0, 1), 1).reflect(Line((0, 0), (1, 1)))
+        Circle(Point2D(1, 0), -1)
+        >>> from sympy import Ellipse, Line, Point
+        >>> Ellipse(Point(3, 4), 1, 3).reflect(Line(Point(0, -4), Point(5, 0)))
+        Traceback (most recent call last):
+        ...
+        NotImplementedError:
+        General Ellipse is not supported but the equation of the reflected
+        Ellipse is given by the zeros of: f(x, y) = (9*x/41 + 40*y/41 +
+        37/41)**2 + (40*x/123 - 3*y/41 - 364/123)**2 - 1
+
+        Notes
+        =====
+
+        Until the general ellipse (with no axis parallel to the x-axis) is
+        supported a NotImplemented error is raised and the equation whose
+        zeros define the rotated ellipse is given.
+
+        """
+
+        if line.slope in (0, oo):
+            c = self.center
+            c = c.reflect(line)
+            return self.func(c, -self.hradius, self.vradius)
+        else:
+            x, y = [uniquely_named_symbol(
+                name, (self, line), modify=lambda s: '_' + s, real=True)
+                for name in 'xy']
+            expr = self.equation(x, y)
+            p = Point(x, y).reflect(line)
+            result = expr.subs(zip((x, y), p.args
+                                   ), simultaneous=True)
+            raise NotImplementedError(filldedent(
+                'General Ellipse is not supported but the equation '
+                'of the reflected Ellipse is given by the zeros of: ' +
+                "f(%s, %s) = %s" % (str(x), str(y), str(result))))
+
+    def rotate(self, angle=0, pt=None):
+        """Rotate ``angle`` radians counterclockwise about Point ``pt``.
+
+        Note: since the general ellipse is not supported, only rotations that
+        are integer multiples of pi/2 are allowed.
+
+        Examples
+        ========
+
+        >>> from sympy import Ellipse, pi
+        >>> Ellipse((1, 0), 2, 1).rotate(pi/2)
+        Ellipse(Point2D(0, 1), 1, 2)
+        >>> Ellipse((1, 0), 2, 1).rotate(pi)
+        Ellipse(Point2D(-1, 0), 2, 1)
+        """
+        if self.hradius == self.vradius:
+            return self.func(self.center.rotate(angle, pt), self.hradius)
+        if (angle/S.Pi).is_integer:
+            return super().rotate(angle, pt)
+        if (2*angle/S.Pi).is_integer:
+            return self.func(self.center.rotate(angle, pt), self.vradius, self.hradius)
+        # XXX see https://github.com/sympy/sympy/issues/2815 for general ellipes
+        raise NotImplementedError('Only rotations of pi/2 are currently supported for Ellipse.')
+
+    def scale(self, x=1, y=1, pt=None):
+        """Override GeometryEntity.scale since it is the major and minor
+        axes which must be scaled and they are not GeometryEntities.
+
+        Examples
+        ========
+
+        >>> from sympy import Ellipse
+        >>> Ellipse((0, 0), 2, 1).scale(2, 4)
+        Circle(Point2D(0, 0), 4)
+        >>> Ellipse((0, 0), 2, 1).scale(2)
+        Ellipse(Point2D(0, 0), 4, 1)
+        """
+        c = self.center
+        if pt:
+            pt = Point(pt, dim=2)
+            return self.translate(*(-pt).args).scale(x, y).translate(*pt.args)
+        h = self.hradius
+        v = self.vradius
+        return self.func(c.scale(x, y), hradius=h*x, vradius=v*y)
+
+    def tangent_lines(self, p):
+        """Tangent lines between `p` and the ellipse.
+
+        If `p` is on the ellipse, returns the tangent line through point `p`.
+        Otherwise, returns the tangent line(s) from `p` to the ellipse, or
+        None if no tangent line is possible (e.g., `p` inside ellipse).
+
+        Parameters
+        ==========
+
+        p : Point
+
+        Returns
+        =======
+
+        tangent_lines : list with 1 or 2 Lines
+
+        Raises
+        ======
+
+        NotImplementedError
+            Can only find tangent lines for a point, `p`, on the ellipse.
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point, sympy.geometry.line.Line
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> e1 = Ellipse(Point(0, 0), 3, 2)
+        >>> e1.tangent_lines(Point(3, 0))
+        [Line2D(Point2D(3, 0), Point2D(3, -12))]
+
+        """
+        p = Point(p, dim=2)
+        if self.encloses_point(p):
+            return []
+
+        if p in self:
+            delta = self.center - p
+            rise = (self.vradius**2)*delta.x
+            run = -(self.hradius**2)*delta.y
+            p2 = Point(simplify(p.x + run),
+                       simplify(p.y + rise))
+            return [Line(p, p2)]
+        else:
+            if len(self.foci) == 2:
+                f1, f2 = self.foci
+                maj = self.hradius
+                test = (2*maj -
+                        Point.distance(f1, p) -
+                        Point.distance(f2, p))
+            else:
+                test = self.radius - Point.distance(self.center, p)
+            if test.is_number and test.is_positive:
+                return []
+            # else p is outside the ellipse or we can't tell. In case of the
+            # latter, the solutions returned will only be valid if
+            # the point is not inside the ellipse; if it is, nan will result.
+            eq = self.equation(x, y)
+            dydx = idiff(eq, y, x)
+            slope = Line(p, Point(x, y)).slope
+
+            # TODO: Replace solve with solveset, when this line is tested
+            tangent_points = solve([slope - dydx, eq], [x, y])
+
+            # handle horizontal and vertical tangent lines
+            if len(tangent_points) == 1:
+                if tangent_points[0][
+                           0] == p.x or tangent_points[0][1] == p.y:
+                    return [Line(p, p + Point(1, 0)), Line(p, p + Point(0, 1))]
+                else:
+                    return [Line(p, p + Point(0, 1)), Line(p, tangent_points[0])]
+
+            # others
+            return [Line(p, tangent_points[0]), Line(p, tangent_points[1])]
+
+    @property
+    def vradius(self):
+        """The vertical radius of the ellipse.
+
+        Returns
+        =======
+
+        vradius : number
+
+        See Also
+        ========
+
+        hradius, major, minor
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> p1 = Point(0, 0)
+        >>> e1 = Ellipse(p1, 3, 1)
+        >>> e1.vradius
+        1
+
+        """
+        return self.args[2]
+
+
+    def second_moment_of_area(self, point=None):
+        """Returns the second moment and product moment area of an ellipse.
+
+        Parameters
+        ==========
+
+        point : Point, two-tuple of sympifiable objects, or None(default=None)
+            point is the point about which second moment of area is to be found.
+            If "point=None" it will be calculated about the axis passing through the
+            centroid of the ellipse.
+
+        Returns
+        =======
+
+        I_xx, I_yy, I_xy : number or SymPy expression
+            I_xx, I_yy are second moment of area of an ellise.
+            I_xy is product moment of area of an ellipse.
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ellipse
+        >>> p1 = Point(0, 0)
+        >>> e1 = Ellipse(p1, 3, 1)
+        >>> e1.second_moment_of_area()
+        (3*pi/4, 27*pi/4, 0)
+
+        References
+        ==========
+
+        .. [1] https://en.wikipedia.org/wiki/List_of_second_moments_of_area
+
+        """
+
+        I_xx = (S.Pi*(self.hradius)*(self.vradius**3))/4
+        I_yy = (S.Pi*(self.hradius**3)*(self.vradius))/4
+        I_xy = 0
+
+        if point is None:
+            return I_xx, I_yy, I_xy
+
+        # parallel axis theorem
+        I_xx = I_xx + self.area*((point[1] - self.center.y)**2)
+        I_yy = I_yy + self.area*((point[0] - self.center.x)**2)
+        I_xy = I_xy + self.area*(point[0] - self.center.x)*(point[1] - self.center.y)
+
+        return I_xx, I_yy, I_xy
+
+
+    def polar_second_moment_of_area(self):
+        """Returns the polar second moment of area of an Ellipse
+
+        It is a constituent of the second moment of area, linked through
+        the perpendicular axis theorem. While the planar second moment of
+        area describes an object's resistance to deflection (bending) when
+        subjected to a force applied to a plane parallel to the central
+        axis, the polar second moment of area describes an object's
+        resistance to deflection when subjected to a moment applied in a
+        plane perpendicular to the object's central axis (i.e. parallel to
+        the cross-section)
+
+        Examples
+        ========
+
+        >>> from sympy import symbols, Circle, Ellipse
+        >>> c = Circle((5, 5), 4)
+        >>> c.polar_second_moment_of_area()
+        128*pi
+        >>> a, b = symbols('a, b')
+        >>> e = Ellipse((0, 0), a, b)
+        >>> e.polar_second_moment_of_area()
+        pi*a**3*b/4 + pi*a*b**3/4
+
+        References
+        ==========
+
+        .. [1] https://en.wikipedia.org/wiki/Polar_moment_of_inertia
+
+        """
+        second_moment = self.second_moment_of_area()
+        return second_moment[0] + second_moment[1]
+
+
+    def section_modulus(self, point=None):
+        """Returns a tuple with the section modulus of an ellipse
+
+        Section modulus is a geometric property of an ellipse defined as the
+        ratio of second moment of area to the distance of the extreme end of
+        the ellipse from the centroidal axis.
+
+        Parameters
+        ==========
+
+        point : Point, two-tuple of sympifyable objects, or None(default=None)
+            point is the point at which section modulus is to be found.
+            If "point=None" section modulus will be calculated for the
+            point farthest from the centroidal axis of the ellipse.
+
+        Returns
+        =======
+
+        S_x, S_y: numbers or SymPy expressions
+                  S_x is the section modulus with respect to the x-axis
+                  S_y is the section modulus with respect to the y-axis
+                  A negative sign indicates that the section modulus is
+                  determined for a point below the centroidal axis.
+
+        Examples
+        ========
+
+        >>> from sympy import Symbol, Ellipse, Circle, Point2D
+        >>> d = Symbol('d', positive=True)
+        >>> c = Circle((0, 0), d/2)
+        >>> c.section_modulus()
+        (pi*d**3/32, pi*d**3/32)
+        >>> e = Ellipse(Point2D(0, 0), 2, 4)
+        >>> e.section_modulus()
+        (8*pi, 4*pi)
+        >>> e.section_modulus((2, 2))
+        (16*pi, 4*pi)
+
+        References
+        ==========
+
+        .. [1] https://en.wikipedia.org/wiki/Section_modulus
+
+        """
+        x_c, y_c = self.center
+        if point is None:
+            # taking x and y as maximum distances from centroid
+            x_min, y_min, x_max, y_max = self.bounds
+            y = max(y_c - y_min, y_max - y_c)
+            x = max(x_c - x_min, x_max - x_c)
+        else:
+            # taking x and y as distances of the given point from the center
+            point = Point2D(point)
+            y = point.y - y_c
+            x = point.x - x_c
+
+        second_moment = self.second_moment_of_area()
+        S_x = second_moment[0]/y
+        S_y = second_moment[1]/x
+
+        return S_x, S_y
+
+
+class Circle(Ellipse):
+    r"""A circle in space.
+
+    Constructed simply from a center and a radius, from three
+    non-collinear points, or the equation of a circle.
+
+    Parameters
+    ==========
+
+    center : Point
+    radius : number or SymPy expression
+    points : sequence of three Points
+    equation : equation of a circle
+
+    Attributes
+    ==========
+
+    radius (synonymous with hradius, vradius, major and minor)
+    circumference
+    equation
+
+    Raises
+    ======
+
+    GeometryError
+        When the given equation is not that of a circle.
+        When trying to construct circle from incorrect parameters.
+
+    See Also
+    ========
+
+    Ellipse, sympy.geometry.point.Point
+
+    Examples
+    ========
+
+    >>> from sympy import Point, Circle, Eq
+    >>> from sympy.abc import x, y, a, b
+
+    A circle constructed from a center and radius:
+
+    >>> c1 = Circle(Point(0, 0), 5)
+    >>> c1.hradius, c1.vradius, c1.radius
+    (5, 5, 5)
+
+    A circle constructed from three points:
+
+    >>> c2 = Circle(Point(0, 0), Point(1, 1), Point(1, 0))
+    >>> c2.hradius, c2.vradius, c2.radius, c2.center
+    (sqrt(2)/2, sqrt(2)/2, sqrt(2)/2, Point2D(1/2, 1/2))
+
+    A circle can be constructed from an equation in the form
+    `ax^2 + by^2 + gx + hy + c = 0`, too:
+
+    >>> Circle(x**2 + y**2 - 25)
+    Circle(Point2D(0, 0), 5)
+
+    If the variables corresponding to x and y are named something
+    else, their name or symbol can be supplied:
+
+    >>> Circle(Eq(a**2 + b**2, 25), x='a', y=b)
+    Circle(Point2D(0, 0), 5)
+    """
+
+    def __new__(cls, *args, **kwargs):
+        evaluate = kwargs.get('evaluate', global_parameters.evaluate)
+        if len(args) == 1 and isinstance(args[0], (Expr, Eq)):
+            x = kwargs.get('x', 'x')
+            y = kwargs.get('y', 'y')
+            equation = args[0].expand()
+            if isinstance(equation, Eq):
+                equation = equation.lhs - equation.rhs
+            x = find(x, equation)
+            y = find(y, equation)
+
+            try:
+                a, b, c, d, e = linear_coeffs(equation, x**2, y**2, x, y)
+            except ValueError:
+                raise GeometryError("The given equation is not that of a circle.")
+
+            if S.Zero in (a, b) or a != b:
+                raise GeometryError("The given equation is not that of a circle.")
+
+            center_x = -c/a/2
+            center_y = -d/b/2
+            r2 = (center_x**2) + (center_y**2) - e/a
+
+            return Circle((center_x, center_y), sqrt(r2), evaluate=evaluate)
+
+        else:
+            c, r = None, None
+            if len(args) == 3:
+                args = [Point(a, dim=2, evaluate=evaluate) for a in args]
+                t = Triangle(*args)
+                if not isinstance(t, Triangle):
+                    return t
+                c = t.circumcenter
+                r = t.circumradius
+            elif len(args) == 2:
+                # Assume (center, radius) pair
+                c = Point(args[0], dim=2, evaluate=evaluate)
+                r = args[1]
+                # this will prohibit imaginary radius
+                try:
+                    r = Point(r, 0, evaluate=evaluate).x
+                except ValueError:
+                    raise GeometryError("Circle with imaginary radius is not permitted")
+
+            if not (c is None or r is None):
+                if r == 0:
+                    return c
+                return GeometryEntity.__new__(cls, c, r, **kwargs)
+
+            raise GeometryError("Circle.__new__ received unknown arguments")
+
+    def _eval_evalf(self, prec=15, **options):
+        pt, r = self.args
+        dps = prec_to_dps(prec)
+        pt = pt.evalf(n=dps, **options)
+        r = r.evalf(n=dps, **options)
+        return self.func(pt, r, evaluate=False)
+
+    @property
+    def circumference(self):
+        """The circumference of the circle.
+
+        Returns
+        =======
+
+        circumference : number or SymPy expression
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Circle
+        >>> c1 = Circle(Point(3, 4), 6)
+        >>> c1.circumference
+        12*pi
+
+        """
+        return 2 * S.Pi * self.radius
+
+    def equation(self, x='x', y='y'):
+        """The equation of the circle.
+
+        Parameters
+        ==========
+
+        x : str or Symbol, optional
+            Default value is 'x'.
+        y : str or Symbol, optional
+            Default value is 'y'.
+
+        Returns
+        =======
+
+        equation : SymPy expression
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Circle
+        >>> c1 = Circle(Point(0, 0), 5)
+        >>> c1.equation()
+        x**2 + y**2 - 25
+
+        """
+        x = _symbol(x, real=True)
+        y = _symbol(y, real=True)
+        t1 = (x - self.center.x)**2
+        t2 = (y - self.center.y)**2
+        return t1 + t2 - self.major**2
+
+    def intersection(self, o):
+        """The intersection of this circle with another geometrical entity.
+
+        Parameters
+        ==========
+
+        o : GeometryEntity
+
+        Returns
+        =======
+
+        intersection : list of GeometryEntities
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Circle, Line, Ray
+        >>> p1, p2, p3 = Point(0, 0), Point(5, 5), Point(6, 0)
+        >>> p4 = Point(5, 0)
+        >>> c1 = Circle(p1, 5)
+        >>> c1.intersection(p2)
+        []
+        >>> c1.intersection(p4)
+        [Point2D(5, 0)]
+        >>> c1.intersection(Ray(p1, p2))
+        [Point2D(5*sqrt(2)/2, 5*sqrt(2)/2)]
+        >>> c1.intersection(Line(p2, p3))
+        []
+
+        """
+        return Ellipse.intersection(self, o)
+
+    @property
+    def radius(self):
+        """The radius of the circle.
+
+        Returns
+        =======
+
+        radius : number or SymPy expression
+
+        See Also
+        ========
+
+        Ellipse.major, Ellipse.minor, Ellipse.hradius, Ellipse.vradius
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Circle
+        >>> c1 = Circle(Point(3, 4), 6)
+        >>> c1.radius
+        6
+
+        """
+        return self.args[1]
+
+    def reflect(self, line):
+        """Override GeometryEntity.reflect since the radius
+        is not a GeometryEntity.
+
+        Examples
+        ========
+
+        >>> from sympy import Circle, Line
+        >>> Circle((0, 1), 1).reflect(Line((0, 0), (1, 1)))
+        Circle(Point2D(1, 0), -1)
+        """
+        c = self.center
+        c = c.reflect(line)
+        return self.func(c, -self.radius)
+
+    def scale(self, x=1, y=1, pt=None):
+        """Override GeometryEntity.scale since the radius
+        is not a GeometryEntity.
+
+        Examples
+        ========
+
+        >>> from sympy import Circle
+        >>> Circle((0, 0), 1).scale(2, 2)
+        Circle(Point2D(0, 0), 2)
+        >>> Circle((0, 0), 1).scale(2, 4)
+        Ellipse(Point2D(0, 0), 2, 4)
+        """
+        c = self.center
+        if pt:
+            pt = Point(pt, dim=2)
+            return self.translate(*(-pt).args).scale(x, y).translate(*pt.args)
+        c = c.scale(x, y)
+        x, y = [abs(i) for i in (x, y)]
+        if x == y:
+            return self.func(c, x*self.radius)
+        h = v = self.radius
+        return Ellipse(c, hradius=h*x, vradius=v*y)
+
+    @property
+    def vradius(self):
+        """
+        This Ellipse property is an alias for the Circle's radius.
+
+        Whereas hradius, major and minor can use Ellipse's conventions,
+        the vradius does not exist for a circle. It is always a positive
+        value in order that the Circle, like Polygons, will have an
+        area that can be positive or negative as determined by the sign
+        of the hradius.
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Circle
+        >>> c1 = Circle(Point(3, 4), 6)
+        >>> c1.vradius
+        6
+        """
+        return abs(self.radius)
+
+
+from .polygon import Polygon, Triangle

.venv/lib/python3.13/site-packages/sympy/geometry/entity.py

@@ -0,0 +1,641 @@
+"""The definition of the base geometrical entity with attributes common to
+all derived geometrical entities.
+
+Contains
+========
+
+GeometryEntity
+GeometricSet
+
+Notes
+=====
+
+A GeometryEntity is any object that has special geometric properties.
+A GeometrySet is a superclass of any GeometryEntity that can also
+be viewed as a sympy.sets.Set.  In particular, points are the only
+GeometryEntity not considered a Set.
+
+Rn is a GeometrySet representing n-dimensional Euclidean space. R2 and
+R3 are currently the only ambient spaces implemented.
+
+"""
+from __future__ import annotations
+
+from sympy.core.basic import Basic
+from sympy.core.containers import Tuple
+from sympy.core.evalf import EvalfMixin, N
+from sympy.core.numbers import oo
+from sympy.core.symbol import Dummy
+from sympy.core.sympify import sympify
+from sympy.functions.elementary.trigonometric import cos, sin, atan
+from sympy.matrices import eye
+from sympy.multipledispatch import dispatch
+from sympy.printing import sstr
+from sympy.sets import Set, Union, FiniteSet
+from sympy.sets.handlers.intersection import intersection_sets
+from sympy.sets.handlers.union import union_sets
+from sympy.solvers.solvers import solve
+from sympy.utilities.misc import func_name
+from sympy.utilities.iterables import is_sequence
+
+
+# How entities are ordered; used by __cmp__ in GeometryEntity
+ordering_of_classes = [
+    "Point2D",
+    "Point3D",
+    "Point",
+    "Segment2D",
+    "Ray2D",
+    "Line2D",
+    "Segment3D",
+    "Line3D",
+    "Ray3D",
+    "Segment",
+    "Ray",
+    "Line",
+    "Plane",
+    "Triangle",
+    "RegularPolygon",
+    "Polygon",
+    "Circle",
+    "Ellipse",
+    "Curve",
+    "Parabola"
+]
+
+
+x, y = [Dummy('entity_dummy') for i in range(2)]
+T = Dummy('entity_dummy', real=True)
+
+
+class GeometryEntity(Basic, EvalfMixin):
+    """The base class for all geometrical entities.
+
+    This class does not represent any particular geometric entity, it only
+    provides the implementation of some methods common to all subclasses.
+
+    """
+
+    __slots__: tuple[str, ...] = ()
+
+    def __cmp__(self, other):
+        """Comparison of two GeometryEntities."""
+        n1 = self.__class__.__name__
+        n2 = other.__class__.__name__
+        c = (n1 > n2) - (n1 < n2)
+        if not c:
+            return 0
+
+        i1 = -1
+        for cls in self.__class__.__mro__:
+            try:
+                i1 = ordering_of_classes.index(cls.__name__)
+                break
+            except ValueError:
+                i1 = -1
+        if i1 == -1:
+            return c
+
+        i2 = -1
+        for cls in other.__class__.__mro__:
+            try:
+                i2 = ordering_of_classes.index(cls.__name__)
+                break
+            except ValueError:
+                i2 = -1
+        if i2 == -1:
+            return c
+
+        return (i1 > i2) - (i1 < i2)
+
+    def __contains__(self, other):
+        """Subclasses should implement this method for anything more complex than equality."""
+        if type(self) is type(other):
+            return self == other
+        raise NotImplementedError()
+
+    def __getnewargs__(self):
+        """Returns a tuple that will be passed to __new__ on unpickling."""
+        return tuple(self.args)
+
+    def __ne__(self, o):
+        """Test inequality of two geometrical entities."""
+        return not self == o
+
+    def __new__(cls, *args, **kwargs):
+        # Points are sequences, but they should not
+        # be converted to Tuples, so use this detection function instead.
+        def is_seq_and_not_point(a):
+            # we cannot use isinstance(a, Point) since we cannot import Point
+            if hasattr(a, 'is_Point') and a.is_Point:
+                return False
+            return is_sequence(a)
+
+        args = [Tuple(*a) if is_seq_and_not_point(a) else sympify(a) for a in args]
+        return Basic.__new__(cls, *args)
+
+    def __radd__(self, a):
+        """Implementation of reverse add method."""
+        return a.__add__(self)
+
+    def __rtruediv__(self, a):
+        """Implementation of reverse division method."""
+        return a.__truediv__(self)
+
+    def __repr__(self):
+        """String representation of a GeometryEntity that can be evaluated
+        by sympy."""
+        return type(self).__name__ + repr(self.args)
+
+    def __rmul__(self, a):
+        """Implementation of reverse multiplication method."""
+        return a.__mul__(self)
+
+    def __rsub__(self, a):
+        """Implementation of reverse subtraction method."""
+        return a.__sub__(self)
+
+    def __str__(self):
+        """String representation of a GeometryEntity."""
+        return type(self).__name__ + sstr(self.args)
+
+    def _eval_subs(self, old, new):
+        from sympy.geometry.point import Point, Point3D
+        if is_sequence(old) or is_sequence(new):
+            if isinstance(self, Point3D):
+                old = Point3D(old)
+                new = Point3D(new)
+            else:
+                old = Point(old)
+                new = Point(new)
+            return  self._subs(old, new)
+
+    def _repr_svg_(self):
+        """SVG representation of a GeometryEntity suitable for IPython"""
+
+        try:
+            bounds = self.bounds
+        except (NotImplementedError, TypeError):
+            # if we have no SVG representation, return None so IPython
+            # will fall back to the next representation
+            return None
+
+        if not all(x.is_number and x.is_finite for x in bounds):
+            return None
+
+        svg_top = '''<svg xmlns="http://www.w3.org/2000/svg"
+            xmlns:xlink="http://www.w3.org/1999/xlink"
+            width="{1}" height="{2}" viewBox="{0}"
+            preserveAspectRatio="xMinYMin meet">
+            <defs>
+                <marker id="markerCircle" markerWidth="8" markerHeight="8"
+                    refx="5" refy="5" markerUnits="strokeWidth">
+                    <circle cx="5" cy="5" r="1.5" style="stroke: none; fill:#000000;"/>
+                </marker>
+                <marker id="markerArrow" markerWidth="13" markerHeight="13" refx="2" refy="4"
+                       orient="auto" markerUnits="strokeWidth">
+                    <path d="M2,2 L2,6 L6,4" style="fill: #000000;" />
+                </marker>
+                <marker id="markerReverseArrow" markerWidth="13" markerHeight="13" refx="6" refy="4"
+                       orient="auto" markerUnits="strokeWidth">
+                    <path d="M6,2 L6,6 L2,4" style="fill: #000000;" />
+                </marker>
+            </defs>'''
+
+        # Establish SVG canvas that will fit all the data + small space
+        xmin, ymin, xmax, ymax = map(N, bounds)
+        if xmin == xmax and ymin == ymax:
+            # This is a point; buffer using an arbitrary size
+            xmin, ymin, xmax, ymax = xmin - .5, ymin -.5, xmax + .5, ymax + .5
+        else:
+            # Expand bounds by a fraction of the data ranges
+            expand = 0.1  # or 10%; this keeps arrowheads in view (R plots use 4%)
+            widest_part = max([xmax - xmin, ymax - ymin])
+            expand_amount = widest_part * expand
+            xmin -= expand_amount
+            ymin -= expand_amount
+            xmax += expand_amount
+            ymax += expand_amount
+        dx = xmax - xmin
+        dy = ymax - ymin
+        width = min([max([100., dx]), 300])
+        height = min([max([100., dy]), 300])
+
+        scale_factor = 1. if max(width, height) == 0 else max(dx, dy) / max(width, height)
+        try:
+            svg = self._svg(scale_factor)
+        except (NotImplementedError, TypeError):
+            # if we have no SVG representation, return None so IPython
+            # will fall back to the next representation
+            return None
+
+        view_box = "{} {} {} {}".format(xmin, ymin, dx, dy)
+        transform = "matrix(1,0,0,-1,0,{})".format(ymax + ymin)
+        svg_top = svg_top.format(view_box, width, height)
+
+        return svg_top + (
+            '<g transform="{}">{}</g></svg>'
+            ).format(transform, svg)
+
+    def _svg(self, scale_factor=1., fill_color="#66cc99"):
+        """Returns SVG path element for the GeometryEntity.
+
+        Parameters
+        ==========
+
+        scale_factor : float
+            Multiplication factor for the SVG stroke-width.  Default is 1.
+        fill_color : str, optional
+            Hex string for fill color. Default is "#66cc99".
+        """
+        raise NotImplementedError()
+
+    def _sympy_(self):
+        return self
+
+    @property
+    def ambient_dimension(self):
+        """What is the dimension of the space that the object is contained in?"""
+        raise NotImplementedError()
+
+    @property
+    def bounds(self):
+        """Return a tuple (xmin, ymin, xmax, ymax) representing the bounding
+        rectangle for the geometric figure.
+
+        """
+
+        raise NotImplementedError()
+
+    def encloses(self, o):
+        """
+        Return True if o is inside (not on or outside) the boundaries of self.
+
+        The object will be decomposed into Points and individual Entities need
+        only define an encloses_point method for their class.
+
+        See Also
+        ========
+
+        sympy.geometry.ellipse.Ellipse.encloses_point
+        sympy.geometry.polygon.Polygon.encloses_point
+
+        Examples
+        ========
+
+        >>> from sympy import RegularPolygon, Point, Polygon
+        >>> t  = Polygon(*RegularPolygon(Point(0, 0), 1, 3).vertices)
+        >>> t2 = Polygon(*RegularPolygon(Point(0, 0), 2, 3).vertices)
+        >>> t2.encloses(t)
+        True
+        >>> t.encloses(t2)
+        False
+
+        """
+
+        from sympy.geometry.point import Point
+        from sympy.geometry.line import Segment, Ray, Line
+        from sympy.geometry.ellipse import Ellipse
+        from sympy.geometry.polygon import Polygon, RegularPolygon
+
+        if isinstance(o, Point):
+            return self.encloses_point(o)
+        elif isinstance(o, Segment):
+            return all(self.encloses_point(x) for x in o.points)
+        elif isinstance(o, (Ray, Line)):
+            return False
+        elif isinstance(o, Ellipse):
+            return self.encloses_point(o.center) and \
+                self.encloses_point(
+                Point(o.center.x + o.hradius, o.center.y)) and \
+                not self.intersection(o)
+        elif isinstance(o, Polygon):
+            if isinstance(o, RegularPolygon):
+                if not self.encloses_point(o.center):
+                    return False
+            return all(self.encloses_point(v) for v in o.vertices)
+        raise NotImplementedError()
+
+    def equals(self, o):
+        return self == o
+
+    def intersection(self, o):
+        """
+        Returns a list of all of the intersections of self with o.
+
+        Notes
+        =====
+
+        An entity is not required to implement this method.
+
+        If two different types of entities can intersect, the item with
+        higher index in ordering_of_classes should implement
+        intersections with anything having a lower index.
+
+        See Also
+        ========
+
+        sympy.geometry.util.intersection
+
+        """
+        raise NotImplementedError()
+
+    def is_similar(self, other):
+        """Is this geometrical entity similar to another geometrical entity?
+
+        Two entities are similar if a uniform scaling (enlarging or
+        shrinking) of one of the entities will allow one to obtain the other.
+
+        Notes
+        =====
+
+        This method is not intended to be used directly but rather
+        through the `are_similar` function found in util.py.
+        An entity is not required to implement this method.
+        If two different types of entities can be similar, it is only
+        required that one of them be able to determine this.
+
+        See Also
+        ========
+
+        scale
+
+        """
+        raise NotImplementedError()
+
+    def reflect(self, line):
+        """
+        Reflects an object across a line.
+
+        Parameters
+        ==========
+
+        line: Line
+
+        Examples
+        ========
+
+        >>> from sympy import pi, sqrt, Line, RegularPolygon
+        >>> l = Line((0, pi), slope=sqrt(2))
+        >>> pent = RegularPolygon((1, 2), 1, 5)
+        >>> rpent = pent.reflect(l)
+        >>> rpent
+        RegularPolygon(Point2D(-2*sqrt(2)*pi/3 - 1/3 + 4*sqrt(2)/3, 2/3 + 2*sqrt(2)/3 + 2*pi/3), -1, 5, -atan(2*sqrt(2)) + 3*pi/5)
+
+        >>> from sympy import pi, Line, Circle, Point
+        >>> l = Line((0, pi), slope=1)
+        >>> circ = Circle(Point(0, 0), 5)
+        >>> rcirc = circ.reflect(l)
+        >>> rcirc
+        Circle(Point2D(-pi, pi), -5)
+
+        """
+        from sympy.geometry.point import Point
+
+        g = self
+        l = line
+        o = Point(0, 0)
+        if l.slope.is_zero:
+            v = l.args[0].y
+            if not v:  # x-axis
+                return g.scale(y=-1)
+            reps = [(p, p.translate(y=2*(v - p.y))) for p in g.atoms(Point)]
+        elif l.slope is oo:
+            v = l.args[0].x
+            if not v:  # y-axis
+                return g.scale(x=-1)
+            reps = [(p, p.translate(x=2*(v - p.x))) for p in g.atoms(Point)]
+        else:
+            if not hasattr(g, 'reflect') and not all(
+                    isinstance(arg, Point) for arg in g.args):
+                raise NotImplementedError(
+                    'reflect undefined or non-Point args in %s' % g)
+            a = atan(l.slope)
+            c = l.coefficients
+            d = -c[-1]/c[1]  # y-intercept
+            # apply the transform to a single point
+            xf = Point(x, y)
+            xf = xf.translate(y=-d).rotate(-a, o).scale(y=-1
+                ).rotate(a, o).translate(y=d)
+            # replace every point using that transform
+            reps = [(p, xf.xreplace({x: p.x, y: p.y})) for p in g.atoms(Point)]
+        return g.xreplace(dict(reps))
+
+    def rotate(self, angle, pt=None):
+        """Rotate ``angle`` radians counterclockwise about Point ``pt``.
+
+        The default pt is the origin, Point(0, 0)
+
+        See Also
+        ========
+
+        scale, translate
+
+        Examples
+        ========
+
+        >>> from sympy import Point, RegularPolygon, Polygon, pi
+        >>> t = Polygon(*RegularPolygon(Point(0, 0), 1, 3).vertices)
+        >>> t # vertex on x axis
+        Triangle(Point2D(1, 0), Point2D(-1/2, sqrt(3)/2), Point2D(-1/2, -sqrt(3)/2))
+        >>> t.rotate(pi/2) # vertex on y axis now
+        Triangle(Point2D(0, 1), Point2D(-sqrt(3)/2, -1/2), Point2D(sqrt(3)/2, -1/2))
+
+        """
+        newargs = []
+        for a in self.args:
+            if isinstance(a, GeometryEntity):
+                newargs.append(a.rotate(angle, pt))
+            else:
+                newargs.append(a)
+        return type(self)(*newargs)
+
+    def scale(self, x=1, y=1, pt=None):
+        """Scale the object by multiplying the x,y-coordinates by x and y.
+
+        If pt is given, the scaling is done relative to that point; the
+        object is shifted by -pt, scaled, and shifted by pt.
+
+        See Also
+        ========
+
+        rotate, translate
+
+        Examples
+        ========
+
+        >>> from sympy import RegularPolygon, Point, Polygon
+        >>> t = Polygon(*RegularPolygon(Point(0, 0), 1, 3).vertices)
+        >>> t
+        Triangle(Point2D(1, 0), Point2D(-1/2, sqrt(3)/2), Point2D(-1/2, -sqrt(3)/2))
+        >>> t.scale(2)
+        Triangle(Point2D(2, 0), Point2D(-1, sqrt(3)/2), Point2D(-1, -sqrt(3)/2))
+        >>> t.scale(2, 2)
+        Triangle(Point2D(2, 0), Point2D(-1, sqrt(3)), Point2D(-1, -sqrt(3)))
+
+        """
+        from sympy.geometry.point import Point
+        if pt:
+            pt = Point(pt, dim=2)
+            return self.translate(*(-pt).args).scale(x, y).translate(*pt.args)
+        return type(self)(*[a.scale(x, y) for a in self.args])  # if this fails, override this class
+
+    def translate(self, x=0, y=0):
+        """Shift the object by adding to the x,y-coordinates the values x and y.
+
+        See Also
+        ========
+
+        rotate, scale
+
+        Examples
+        ========
+
+        >>> from sympy import RegularPolygon, Point, Polygon
+        >>> t = Polygon(*RegularPolygon(Point(0, 0), 1, 3).vertices)
+        >>> t
+        Triangle(Point2D(1, 0), Point2D(-1/2, sqrt(3)/2), Point2D(-1/2, -sqrt(3)/2))
+        >>> t.translate(2)
+        Triangle(Point2D(3, 0), Point2D(3/2, sqrt(3)/2), Point2D(3/2, -sqrt(3)/2))
+        >>> t.translate(2, 2)
+        Triangle(Point2D(3, 2), Point2D(3/2, sqrt(3)/2 + 2), Point2D(3/2, 2 - sqrt(3)/2))
+
+        """
+        newargs = []
+        for a in self.args:
+            if isinstance(a, GeometryEntity):
+                newargs.append(a.translate(x, y))
+            else:
+                newargs.append(a)
+        return self.func(*newargs)
+
+    def parameter_value(self, other, t):
+        """Return the parameter corresponding to the given point.
+        Evaluating an arbitrary point of the entity at this parameter
+        value will return the given point.
+
+        Examples
+        ========
+
+        >>> from sympy import Line, Point
+        >>> from sympy.abc import t
+        >>> a = Point(0, 0)
+        >>> b = Point(2, 2)
+        >>> Line(a, b).parameter_value((1, 1), t)
+        {t: 1/2}
+        >>> Line(a, b).arbitrary_point(t).subs(_)
+        Point2D(1, 1)
+        """
+        from sympy.geometry.point import Point
+        if not isinstance(other, GeometryEntity):
+            other = Point(other, dim=self.ambient_dimension)
+        if not isinstance(other, Point):
+            raise ValueError("other must be a point")
+        sol = solve(self.arbitrary_point(T) - other, T, dict=True)
+        if not sol:
+            raise ValueError("Given point is not on %s" % func_name(self))
+        return {t: sol[0][T]}
+
+
+class GeometrySet(GeometryEntity, Set):
+    """Parent class of all GeometryEntity that are also Sets
+    (compatible with sympy.sets)
+    """
+    __slots__ = ()
+
+    def _contains(self, other):
+        """sympy.sets uses the _contains method, so include it for compatibility."""
+
+        if isinstance(other, Set) and other.is_FiniteSet:
+            return all(self.__contains__(i) for i in other)
+
+        return self.__contains__(other)
+
+@dispatch(GeometrySet, Set)  # type:ignore # noqa:F811
+def union_sets(self, o): # noqa:F811
+    """ Returns the union of self and o
+    for use with sympy.sets.Set, if possible. """
+
+
+    # if its a FiniteSet, merge any points
+    # we contain and return a union with the rest
+    if o.is_FiniteSet:
+        other_points = [p for p in o if not self._contains(p)]
+        if len(other_points) == len(o):
+            return None
+        return Union(self, FiniteSet(*other_points))
+    if self._contains(o):
+        return self
+    return None
+
+
+@dispatch(GeometrySet, Set)  # type: ignore # noqa:F811
+def intersection_sets(self, o): # noqa:F811
+    """ Returns a sympy.sets.Set of intersection objects,
+    if possible. """
+
+    from sympy.geometry.point import Point
+
+    try:
+        # if o is a FiniteSet, find the intersection directly
+        # to avoid infinite recursion
+        if o.is_FiniteSet:
+            inter = FiniteSet(*(p for p in o if self.contains(p)))
+        else:
+            inter = self.intersection(o)
+    except NotImplementedError:
+        # sympy.sets.Set.reduce expects None if an object
+        # doesn't know how to simplify
+        return None
+
+    # put the points in a FiniteSet
+    points = FiniteSet(*[p for p in inter if isinstance(p, Point)])
+    non_points = [p for p in inter if not isinstance(p, Point)]
+
+    return Union(*(non_points + [points]))
+
+def translate(x, y):
+    """Return the matrix to translate a 2-D point by x and y."""
+    rv = eye(3)
+    rv[2, 0] = x
+    rv[2, 1] = y
+    return rv
+
+
+def scale(x, y, pt=None):
+    """Return the matrix to multiply a 2-D point's coordinates by x and y.
+
+    If pt is given, the scaling is done relative to that point."""
+    rv = eye(3)
+    rv[0, 0] = x
+    rv[1, 1] = y
+    if pt:
+        from sympy.geometry.point import Point
+        pt = Point(pt, dim=2)
+        tr1 = translate(*(-pt).args)
+        tr2 = translate(*pt.args)
+        return tr1*rv*tr2
+    return rv
+
+
+def rotate(th):
+    """Return the matrix to rotate a 2-D point about the origin by ``angle``.
+
+    The angle is measured in radians. To Point a point about a point other
+    then the origin, translate the Point, do the rotation, and
+    translate it back:
+
+    >>> from sympy.geometry.entity import rotate, translate
+    >>> from sympy import Point, pi
+    >>> rot_about_11 = translate(-1, -1)*rotate(pi/2)*translate(1, 1)
+    >>> Point(1, 1).transform(rot_about_11)
+    Point2D(1, 1)
+    >>> Point(0, 0).transform(rot_about_11)
+    Point2D(2, 0)
+    """
+    s = sin(th)
+    rv = eye(3)*cos(th)
+    rv[0, 1] = s
+    rv[1, 0] = -s
+    rv[2, 2] = 1
+    return rv

.venv/lib/python3.13/site-packages/sympy/geometry/exceptions.py

@@ -0,0 +1,5 @@
+"""Geometry Errors."""
+
+class GeometryError(ValueError):
+    """An exception raised by classes in the geometry module."""
+    pass

.venv/lib/python3.13/site-packages/sympy/geometry/line.py

@@ -0,0 +1,2877 @@
+"""Line-like geometrical entities.
+
+Contains
+========
+LinearEntity
+Line
+Ray
+Segment
+LinearEntity2D
+Line2D
+Ray2D
+Segment2D
+LinearEntity3D
+Line3D
+Ray3D
+Segment3D
+
+"""
+
+from sympy.core.containers import Tuple
+from sympy.core.evalf import N
+from sympy.core.expr import Expr
+from sympy.core.numbers import Rational, oo, Float
+from sympy.core.relational import Eq
+from sympy.core.singleton import S
+from sympy.core.sorting import ordered
+from sympy.core.symbol import _symbol, Dummy, uniquely_named_symbol
+from sympy.core.sympify import sympify
+from sympy.functions.elementary.piecewise import Piecewise
+from sympy.functions.elementary.trigonometric import (_pi_coeff, acos, tan, atan2)
+from .entity import GeometryEntity, GeometrySet
+from .exceptions import GeometryError
+from .point import Point, Point3D
+from .util import find, intersection
+from sympy.logic.boolalg import And
+from sympy.matrices import Matrix
+from sympy.sets.sets import Intersection
+from sympy.simplify.simplify import simplify
+from sympy.solvers.solvers import solve
+from sympy.solvers.solveset import linear_coeffs
+from sympy.utilities.misc import Undecidable, filldedent
+
+
+import random
+
+
+t, u = [Dummy('line_dummy') for i in range(2)]
+
+
+class LinearEntity(GeometrySet):
+    """A base class for all linear entities (Line, Ray and Segment)
+    in n-dimensional Euclidean space.
+
+    Attributes
+    ==========
+
+    ambient_dimension
+    direction
+    length
+    p1
+    p2
+    points
+
+    Notes
+    =====
+
+    This is an abstract class and is not meant to be instantiated.
+
+    See Also
+    ========
+
+    sympy.geometry.entity.GeometryEntity
+
+    """
+    def __new__(cls, p1, p2=None, **kwargs):
+        p1, p2 = Point._normalize_dimension(p1, p2)
+        if p1 == p2:
+            # sometimes we return a single point if we are not given two unique
+            # points. This is done in the specific subclass
+            raise ValueError(
+                "%s.__new__ requires two unique Points." % cls.__name__)
+        if len(p1) != len(p2):
+            raise ValueError(
+                "%s.__new__ requires two Points of equal dimension." % cls.__name__)
+
+        return GeometryEntity.__new__(cls, p1, p2, **kwargs)
+
+    def __contains__(self, other):
+        """Return a definitive answer or else raise an error if it cannot
+        be determined that other is on the boundaries of self."""
+        result = self.contains(other)
+
+        if result is not None:
+            return result
+        else:
+            raise Undecidable(
+                "Cannot decide whether '%s' contains '%s'" % (self, other))
+
+    def _span_test(self, other):
+        """Test whether the point `other` lies in the positive span of `self`.
+        A point x is 'in front' of a point y if x.dot(y) >= 0.  Return
+        -1 if `other` is behind `self.p1`, 0 if `other` is `self.p1` and
+        and 1 if `other` is in front of `self.p1`."""
+        if self.p1 == other:
+            return 0
+
+        rel_pos = other - self.p1
+        d = self.direction
+        if d.dot(rel_pos) > 0:
+            return 1
+        return -1
+
+    @property
+    def ambient_dimension(self):
+        """A property method that returns the dimension of LinearEntity
+        object.
+
+        Parameters
+        ==========
+
+        p1 : LinearEntity
+
+        Returns
+        =======
+
+        dimension : integer
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2 = Point(0, 0), Point(1, 1)
+        >>> l1 = Line(p1, p2)
+        >>> l1.ambient_dimension
+        2
+
+        >>> from sympy import Point, Line
+        >>> p1, p2 = Point(0, 0, 0), Point(1, 1, 1)
+        >>> l1 = Line(p1, p2)
+        >>> l1.ambient_dimension
+        3
+
+        """
+        return len(self.p1)
+
+    def angle_between(l1, l2):
+        """Return the non-reflex angle formed by rays emanating from
+        the origin with directions the same as the direction vectors
+        of the linear entities.
+
+        Parameters
+        ==========
+
+        l1 : LinearEntity
+        l2 : LinearEntity
+
+        Returns
+        =======
+
+        angle : angle in radians
+
+        Notes
+        =====
+
+        From the dot product of vectors v1 and v2 it is known that:
+
+            ``dot(v1, v2) = |v1|*|v2|*cos(A)``
+
+        where A is the angle formed between the two vectors. We can
+        get the directional vectors of the two lines and readily
+        find the angle between the two using the above formula.
+
+        See Also
+        ========
+
+        is_perpendicular, Ray2D.closing_angle
+
+        Examples
+        ========
+
+        >>> from sympy import Line
+        >>> e = Line((0, 0), (1, 0))
+        >>> ne = Line((0, 0), (1, 1))
+        >>> sw = Line((1, 1), (0, 0))
+        >>> ne.angle_between(e)
+        pi/4
+        >>> sw.angle_between(e)
+        3*pi/4
+
+        To obtain the non-obtuse angle at the intersection of lines, use
+        the ``smallest_angle_between`` method:
+
+        >>> sw.smallest_angle_between(e)
+        pi/4
+
+        >>> from sympy import Point3D, Line3D
+        >>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(1, 1, 1), Point3D(-1, 2, 0)
+        >>> l1, l2 = Line3D(p1, p2), Line3D(p2, p3)
+        >>> l1.angle_between(l2)
+        acos(-sqrt(2)/3)
+        >>> l1.smallest_angle_between(l2)
+        acos(sqrt(2)/3)
+        """
+        if not isinstance(l1, LinearEntity) and not isinstance(l2, LinearEntity):
+            raise TypeError('Must pass only LinearEntity objects')
+
+        v1, v2 = l1.direction, l2.direction
+        return acos(v1.dot(v2)/(abs(v1)*abs(v2)))
+
+    def smallest_angle_between(l1, l2):
+        """Return the smallest angle formed at the intersection of the
+        lines containing the linear entities.
+
+        Parameters
+        ==========
+
+        l1 : LinearEntity
+        l2 : LinearEntity
+
+        Returns
+        =======
+
+        angle : angle in radians
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2, p3 = Point(0, 0), Point(0, 4), Point(2, -2)
+        >>> l1, l2 = Line(p1, p2), Line(p1, p3)
+        >>> l1.smallest_angle_between(l2)
+        pi/4
+
+        See Also
+        ========
+
+        angle_between, is_perpendicular, Ray2D.closing_angle
+        """
+        if not isinstance(l1, LinearEntity) and not isinstance(l2, LinearEntity):
+            raise TypeError('Must pass only LinearEntity objects')
+
+        v1, v2 = l1.direction, l2.direction
+        return acos(abs(v1.dot(v2))/(abs(v1)*abs(v2)))
+
+    def arbitrary_point(self, parameter='t'):
+        """A parameterized point on the Line.
+
+        Parameters
+        ==========
+
+        parameter : str, optional
+            The name of the parameter which will be used for the parametric
+            point. The default value is 't'. When this parameter is 0, the
+            first point used to define the line will be returned, and when
+            it is 1 the second point will be returned.
+
+        Returns
+        =======
+
+        point : Point
+
+        Raises
+        ======
+
+        ValueError
+            When ``parameter`` already appears in the Line's definition.
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2 = Point(1, 0), Point(5, 3)
+        >>> l1 = Line(p1, p2)
+        >>> l1.arbitrary_point()
+        Point2D(4*t + 1, 3*t)
+        >>> from sympy import Point3D, Line3D
+        >>> p1, p2 = Point3D(1, 0, 0), Point3D(5, 3, 1)
+        >>> l1 = Line3D(p1, p2)
+        >>> l1.arbitrary_point()
+        Point3D(4*t + 1, 3*t, t)
+
+        """
+        t = _symbol(parameter, real=True)
+        if t.name in (f.name for f in self.free_symbols):
+            raise ValueError(filldedent('''
+                Symbol %s already appears in object
+                and cannot be used as a parameter.
+                ''' % t.name))
+        # multiply on the right so the variable gets
+        # combined with the coordinates of the point
+        return self.p1 + (self.p2 - self.p1)*t
+
+    @staticmethod
+    def are_concurrent(*lines):
+        """Is a sequence of linear entities concurrent?
+
+        Two or more linear entities are concurrent if they all
+        intersect at a single point.
+
+        Parameters
+        ==========
+
+        lines
+            A sequence of linear entities.
+
+        Returns
+        =======
+
+        True : if the set of linear entities intersect in one point
+        False : otherwise.
+
+        See Also
+        ========
+
+        sympy.geometry.util.intersection
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2 = Point(0, 0), Point(3, 5)
+        >>> p3, p4 = Point(-2, -2), Point(0, 2)
+        >>> l1, l2, l3 = Line(p1, p2), Line(p1, p3), Line(p1, p4)
+        >>> Line.are_concurrent(l1, l2, l3)
+        True
+        >>> l4 = Line(p2, p3)
+        >>> Line.are_concurrent(l2, l3, l4)
+        False
+        >>> from sympy import Point3D, Line3D
+        >>> p1, p2 = Point3D(0, 0, 0), Point3D(3, 5, 2)
+        >>> p3, p4 = Point3D(-2, -2, -2), Point3D(0, 2, 1)
+        >>> l1, l2, l3 = Line3D(p1, p2), Line3D(p1, p3), Line3D(p1, p4)
+        >>> Line3D.are_concurrent(l1, l2, l3)
+        True
+        >>> l4 = Line3D(p2, p3)
+        >>> Line3D.are_concurrent(l2, l3, l4)
+        False
+
+        """
+        common_points = Intersection(*lines)
+        if common_points.is_FiniteSet and len(common_points) == 1:
+            return True
+        return False
+
+    def contains(self, other):
+        """Subclasses should implement this method and should return
+            True if other is on the boundaries of self;
+            False if not on the boundaries of self;
+            None if a determination cannot be made."""
+        raise NotImplementedError()
+
+    @property
+    def direction(self):
+        """The direction vector of the LinearEntity.
+
+        Returns
+        =======
+
+        p : a Point; the ray from the origin to this point is the
+            direction of `self`
+
+        Examples
+        ========
+
+        >>> from sympy import Line
+        >>> a, b = (1, 1), (1, 3)
+        >>> Line(a, b).direction
+        Point2D(0, 2)
+        >>> Line(b, a).direction
+        Point2D(0, -2)
+
+        This can be reported so the distance from the origin is 1:
+
+        >>> Line(b, a).direction.unit
+        Point2D(0, -1)
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point.unit
+
+        """
+        return self.p2 - self.p1
+
+    def intersection(self, other):
+        """The intersection with another geometrical entity.
+
+        Parameters
+        ==========
+
+        o : Point or LinearEntity
+
+        Returns
+        =======
+
+        intersection : list of geometrical entities
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line, Segment
+        >>> p1, p2, p3 = Point(0, 0), Point(1, 1), Point(7, 7)
+        >>> l1 = Line(p1, p2)
+        >>> l1.intersection(p3)
+        [Point2D(7, 7)]
+        >>> p4, p5 = Point(5, 0), Point(0, 3)
+        >>> l2 = Line(p4, p5)
+        >>> l1.intersection(l2)
+        [Point2D(15/8, 15/8)]
+        >>> p6, p7 = Point(0, 5), Point(2, 6)
+        >>> s1 = Segment(p6, p7)
+        >>> l1.intersection(s1)
+        []
+        >>> from sympy import Point3D, Line3D, Segment3D
+        >>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(1, 1, 1), Point3D(7, 7, 7)
+        >>> l1 = Line3D(p1, p2)
+        >>> l1.intersection(p3)
+        [Point3D(7, 7, 7)]
+        >>> l1 = Line3D(Point3D(4,19,12), Point3D(5,25,17))
+        >>> l2 = Line3D(Point3D(-3, -15, -19), direction_ratio=[2,8,8])
+        >>> l1.intersection(l2)
+        [Point3D(1, 1, -3)]
+        >>> p6, p7 = Point3D(0, 5, 2), Point3D(2, 6, 3)
+        >>> s1 = Segment3D(p6, p7)
+        >>> l1.intersection(s1)
+        []
+
+        """
+        def intersect_parallel_rays(ray1, ray2):
+            if ray1.direction.dot(ray2.direction) > 0:
+                # rays point in the same direction
+                # so return the one that is "in front"
+                return [ray2] if ray1._span_test(ray2.p1) >= 0 else [ray1]
+            else:
+                # rays point in opposite directions
+                st = ray1._span_test(ray2.p1)
+                if st < 0:
+                    return []
+                elif st == 0:
+                    return [ray2.p1]
+                return [Segment(ray1.p1, ray2.p1)]
+
+        def intersect_parallel_ray_and_segment(ray, seg):
+            st1, st2 = ray._span_test(seg.p1), ray._span_test(seg.p2)
+            if st1 < 0 and st2 < 0:
+                return []
+            elif st1 >= 0 and st2 >= 0:
+                return [seg]
+            elif st1 >= 0:  # st2 < 0:
+                return [Segment(ray.p1, seg.p1)]
+            else:  # st1 < 0 and st2 >= 0:
+                return [Segment(ray.p1, seg.p2)]
+
+        def intersect_parallel_segments(seg1, seg2):
+            if seg1.contains(seg2):
+                return [seg2]
+            if seg2.contains(seg1):
+                return [seg1]
+
+            # direct the segments so they're oriented the same way
+            if seg1.direction.dot(seg2.direction) < 0:
+                seg2 = Segment(seg2.p2, seg2.p1)
+            # order the segments so seg1 is "behind" seg2
+            if seg1._span_test(seg2.p1) < 0:
+                seg1, seg2 = seg2, seg1
+            if seg2._span_test(seg1.p2) < 0:
+                return []
+            return [Segment(seg2.p1, seg1.p2)]
+
+        if not isinstance(other, GeometryEntity):
+            other = Point(other, dim=self.ambient_dimension)
+        if other.is_Point:
+            if self.contains(other):
+                return [other]
+            else:
+                return []
+        elif isinstance(other, LinearEntity):
+            # break into cases based on whether
+            # the lines are parallel, non-parallel intersecting, or skew
+            pts = Point._normalize_dimension(self.p1, self.p2, other.p1, other.p2)
+            rank = Point.affine_rank(*pts)
+
+            if rank == 1:
+                # we're collinear
+                if isinstance(self, Line):
+                    return [other]
+                if isinstance(other, Line):
+                    return [self]
+
+                if isinstance(self, Ray) and isinstance(other, Ray):
+                    return intersect_parallel_rays(self, other)
+                if isinstance(self, Ray) and isinstance(other, Segment):
+                    return intersect_parallel_ray_and_segment(self, other)
+                if isinstance(self, Segment) and isinstance(other, Ray):
+                    return intersect_parallel_ray_and_segment(other, self)
+                if isinstance(self, Segment) and isinstance(other, Segment):
+                    return intersect_parallel_segments(self, other)
+            elif rank == 2:
+                # we're in the same plane
+                l1 = Line(*pts[:2])
+                l2 = Line(*pts[2:])
+
+                # check to see if we're parallel.  If we are, we can't
+                # be intersecting, since the collinear case was already
+                # handled
+                if l1.direction.is_scalar_multiple(l2.direction):
+                    return []
+
+                # find the intersection as if everything were lines
+                # by solving the equation t*d + p1 == s*d' + p1'
+                m = Matrix([l1.direction, -l2.direction]).transpose()
+                v = Matrix([l2.p1 - l1.p1]).transpose()
+
+                # we cannot use m.solve(v) because that only works for square matrices
+                m_rref, pivots = m.col_insert(2, v).rref(simplify=True)
+                # rank == 2 ensures we have 2 pivots, but let's check anyway
+                if len(pivots) != 2:
+                    raise GeometryError("Failed when solving Mx=b when M={} and b={}".format(m, v))
+                coeff = m_rref[0, 2]
+                line_intersection = l1.direction*coeff + self.p1
+
+                # if both are lines, skip a containment check
+                if isinstance(self, Line) and isinstance(other, Line):
+                    return [line_intersection]
+
+                if ((isinstance(self, Line) or
+                     self.contains(line_intersection)) and
+                        other.contains(line_intersection)):
+                    return [line_intersection]
+                if not self.atoms(Float) and not other.atoms(Float):
+                    # if it can fail when there are no Floats then
+                    # maybe the following parametric check should be
+                    # done
+                    return []
+                # floats may fail exact containment so check that the
+                # arbitrary points, when  equal, both give a
+                # non-negative parameter when the arbitrary point
+                # coordinates are equated
+                tu = solve(self.arbitrary_point(t) - other.arbitrary_point(u),
+                    t, u, dict=True)[0]
+                def ok(p, l):
+                    if isinstance(l, Line):
+                        # p > -oo
+                        return True
+                    if isinstance(l, Ray):
+                        # p >= 0
+                        return p.is_nonnegative
+                    if isinstance(l, Segment):
+                        # 0 <= p <= 1
+                        return p.is_nonnegative and (1 - p).is_nonnegative
+                    raise ValueError("unexpected line type")
+                if ok(tu[t], self) and ok(tu[u], other):
+                    return [line_intersection]
+                return []
+            else:
+                # we're skew
+                return []
+
+        return other.intersection(self)
+
+    def is_parallel(l1, l2):
+        """Are two linear entities parallel?
+
+        Parameters
+        ==========
+
+        l1 : LinearEntity
+        l2 : LinearEntity
+
+        Returns
+        =======
+
+        True : if l1 and l2 are parallel,
+        False : otherwise.
+
+        See Also
+        ========
+
+        coefficients
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2 = Point(0, 0), Point(1, 1)
+        >>> p3, p4 = Point(3, 4), Point(6, 7)
+        >>> l1, l2 = Line(p1, p2), Line(p3, p4)
+        >>> Line.is_parallel(l1, l2)
+        True
+        >>> p5 = Point(6, 6)
+        >>> l3 = Line(p3, p5)
+        >>> Line.is_parallel(l1, l3)
+        False
+        >>> from sympy import Point3D, Line3D
+        >>> p1, p2 = Point3D(0, 0, 0), Point3D(3, 4, 5)
+        >>> p3, p4 = Point3D(2, 1, 1), Point3D(8, 9, 11)
+        >>> l1, l2 = Line3D(p1, p2), Line3D(p3, p4)
+        >>> Line3D.is_parallel(l1, l2)
+        True
+        >>> p5 = Point3D(6, 6, 6)
+        >>> l3 = Line3D(p3, p5)
+        >>> Line3D.is_parallel(l1, l3)
+        False
+
+        """
+        if not isinstance(l1, LinearEntity) and not isinstance(l2, LinearEntity):
+            raise TypeError('Must pass only LinearEntity objects')
+
+        return l1.direction.is_scalar_multiple(l2.direction)
+
+    def is_perpendicular(l1, l2):
+        """Are two linear entities perpendicular?
+
+        Parameters
+        ==========
+
+        l1 : LinearEntity
+        l2 : LinearEntity
+
+        Returns
+        =======
+
+        True : if l1 and l2 are perpendicular,
+        False : otherwise.
+
+        See Also
+        ========
+
+        coefficients
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2, p3 = Point(0, 0), Point(1, 1), Point(-1, 1)
+        >>> l1, l2 = Line(p1, p2), Line(p1, p3)
+        >>> l1.is_perpendicular(l2)
+        True
+        >>> p4 = Point(5, 3)
+        >>> l3 = Line(p1, p4)
+        >>> l1.is_perpendicular(l3)
+        False
+        >>> from sympy import Point3D, Line3D
+        >>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(1, 1, 1), Point3D(-1, 2, 0)
+        >>> l1, l2 = Line3D(p1, p2), Line3D(p2, p3)
+        >>> l1.is_perpendicular(l2)
+        False
+        >>> p4 = Point3D(5, 3, 7)
+        >>> l3 = Line3D(p1, p4)
+        >>> l1.is_perpendicular(l3)
+        False
+
+        """
+        if not isinstance(l1, LinearEntity) and not isinstance(l2, LinearEntity):
+            raise TypeError('Must pass only LinearEntity objects')
+
+        return S.Zero.equals(l1.direction.dot(l2.direction))
+
+    def is_similar(self, other):
+        """
+        Return True if self and other are contained in the same line.
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2, p3 = Point(0, 1), Point(3, 4), Point(2, 3)
+        >>> l1 = Line(p1, p2)
+        >>> l2 = Line(p1, p3)
+        >>> l1.is_similar(l2)
+        True
+        """
+        l = Line(self.p1, self.p2)
+        return l.contains(other)
+
+    @property
+    def length(self):
+        """
+        The length of the line.
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2 = Point(0, 0), Point(3, 5)
+        >>> l1 = Line(p1, p2)
+        >>> l1.length
+        oo
+        """
+        return S.Infinity
+
+    @property
+    def p1(self):
+        """The first defining point of a linear entity.
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2 = Point(0, 0), Point(5, 3)
+        >>> l = Line(p1, p2)
+        >>> l.p1
+        Point2D(0, 0)
+
+        """
+        return self.args[0]
+
+    @property
+    def p2(self):
+        """The second defining point of a linear entity.
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2 = Point(0, 0), Point(5, 3)
+        >>> l = Line(p1, p2)
+        >>> l.p2
+        Point2D(5, 3)
+
+        """
+        return self.args[1]
+
+    def parallel_line(self, p):
+        """Create a new Line parallel to this linear entity which passes
+        through the point `p`.
+
+        Parameters
+        ==========
+
+        p : Point
+
+        Returns
+        =======
+
+        line : Line
+
+        See Also
+        ========
+
+        is_parallel
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2, p3 = Point(0, 0), Point(2, 3), Point(-2, 2)
+        >>> l1 = Line(p1, p2)
+        >>> l2 = l1.parallel_line(p3)
+        >>> p3 in l2
+        True
+        >>> l1.is_parallel(l2)
+        True
+        >>> from sympy import Point3D, Line3D
+        >>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(2, 3, 4), Point3D(-2, 2, 0)
+        >>> l1 = Line3D(p1, p2)
+        >>> l2 = l1.parallel_line(p3)
+        >>> p3 in l2
+        True
+        >>> l1.is_parallel(l2)
+        True
+
+        """
+        p = Point(p, dim=self.ambient_dimension)
+        return Line(p, p + self.direction)
+
+    def perpendicular_line(self, p):
+        """Create a new Line perpendicular to this linear entity which passes
+        through the point `p`.
+
+        Parameters
+        ==========
+
+        p : Point
+
+        Returns
+        =======
+
+        line : Line
+
+        See Also
+        ========
+
+        sympy.geometry.line.LinearEntity.is_perpendicular, perpendicular_segment
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D, Line3D
+        >>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(2, 3, 4), Point3D(-2, 2, 0)
+        >>> L = Line3D(p1, p2)
+        >>> P = L.perpendicular_line(p3); P
+        Line3D(Point3D(-2, 2, 0), Point3D(4/29, 6/29, 8/29))
+        >>> L.is_perpendicular(P)
+        True
+
+        In 3D the, the first point used to define the line is the point
+        through which the perpendicular was required to pass; the
+        second point is (arbitrarily) contained in the given line:
+
+        >>> P.p2 in L
+        True
+        """
+        p = Point(p, dim=self.ambient_dimension)
+        if p in self:
+            p = p + self.direction.orthogonal_direction
+        return Line(p, self.projection(p))
+
+    def perpendicular_segment(self, p):
+        """Create a perpendicular line segment from `p` to this line.
+
+        The endpoints of the segment are ``p`` and the closest point in
+        the line containing self. (If self is not a line, the point might
+        not be in self.)
+
+        Parameters
+        ==========
+
+        p : Point
+
+        Returns
+        =======
+
+        segment : Segment
+
+        Notes
+        =====
+
+        Returns `p` itself if `p` is on this linear entity.
+
+        See Also
+        ========
+
+        perpendicular_line
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2, p3 = Point(0, 0), Point(1, 1), Point(0, 2)
+        >>> l1 = Line(p1, p2)
+        >>> s1 = l1.perpendicular_segment(p3)
+        >>> l1.is_perpendicular(s1)
+        True
+        >>> p3 in s1
+        True
+        >>> l1.perpendicular_segment(Point(4, 0))
+        Segment2D(Point2D(4, 0), Point2D(2, 2))
+        >>> from sympy import Point3D, Line3D
+        >>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(1, 1, 1), Point3D(0, 2, 0)
+        >>> l1 = Line3D(p1, p2)
+        >>> s1 = l1.perpendicular_segment(p3)
+        >>> l1.is_perpendicular(s1)
+        True
+        >>> p3 in s1
+        True
+        >>> l1.perpendicular_segment(Point3D(4, 0, 0))
+        Segment3D(Point3D(4, 0, 0), Point3D(4/3, 4/3, 4/3))
+
+        """
+        p = Point(p, dim=self.ambient_dimension)
+        if p in self:
+            return p
+        l = self.perpendicular_line(p)
+        # The intersection should be unique, so unpack the singleton
+        p2, = Intersection(Line(self.p1, self.p2), l)
+
+        return Segment(p, p2)
+
+    @property
+    def points(self):
+        """The two points used to define this linear entity.
+
+        Returns
+        =======
+
+        points : tuple of Points
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2 = Point(0, 0), Point(5, 11)
+        >>> l1 = Line(p1, p2)
+        >>> l1.points
+        (Point2D(0, 0), Point2D(5, 11))
+
+        """
+        return (self.p1, self.p2)
+
+    def projection(self, other):
+        """Project a point, line, ray, or segment onto this linear entity.
+
+        Parameters
+        ==========
+
+        other : Point or LinearEntity (Line, Ray, Segment)
+
+        Returns
+        =======
+
+        projection : Point or LinearEntity (Line, Ray, Segment)
+            The return type matches the type of the parameter ``other``.
+
+        Raises
+        ======
+
+        GeometryError
+            When method is unable to perform projection.
+
+        Notes
+        =====
+
+        A projection involves taking the two points that define
+        the linear entity and projecting those points onto a
+        Line and then reforming the linear entity using these
+        projections.
+        A point P is projected onto a line L by finding the point
+        on L that is closest to P. This point is the intersection
+        of L and the line perpendicular to L that passes through P.
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point, perpendicular_line
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line, Segment, Rational
+        >>> p1, p2, p3 = Point(0, 0), Point(1, 1), Point(Rational(1, 2), 0)
+        >>> l1 = Line(p1, p2)
+        >>> l1.projection(p3)
+        Point2D(1/4, 1/4)
+        >>> p4, p5 = Point(10, 0), Point(12, 1)
+        >>> s1 = Segment(p4, p5)
+        >>> l1.projection(s1)
+        Segment2D(Point2D(5, 5), Point2D(13/2, 13/2))
+        >>> p1, p2, p3 = Point(0, 0, 1), Point(1, 1, 2), Point(2, 0, 1)
+        >>> l1 = Line(p1, p2)
+        >>> l1.projection(p3)
+        Point3D(2/3, 2/3, 5/3)
+        >>> p4, p5 = Point(10, 0, 1), Point(12, 1, 3)
+        >>> s1 = Segment(p4, p5)
+        >>> l1.projection(s1)
+        Segment3D(Point3D(10/3, 10/3, 13/3), Point3D(5, 5, 6))
+
+        """
+        if not isinstance(other, GeometryEntity):
+            other = Point(other, dim=self.ambient_dimension)
+
+        def proj_point(p):
+            return Point.project(p - self.p1, self.direction) + self.p1
+
+        if isinstance(other, Point):
+            return proj_point(other)
+        elif isinstance(other, LinearEntity):
+            p1, p2 = proj_point(other.p1), proj_point(other.p2)
+            # test to see if we're degenerate
+            if p1 == p2:
+                return p1
+            projected = other.__class__(p1, p2)
+            projected = Intersection(self, projected)
+            if projected.is_empty:
+                return projected
+            # if we happen to have intersected in only a point, return that
+            if projected.is_FiniteSet and len(projected) == 1:
+                # projected is a set of size 1, so unpack it in `a`
+                a, = projected
+                return a
+            # order args so projection is in the same direction as self
+            if self.direction.dot(projected.direction) < 0:
+                p1, p2 = projected.args
+                projected = projected.func(p2, p1)
+            return projected
+
+        raise GeometryError(
+            "Do not know how to project %s onto %s" % (other, self))
+
+    def random_point(self, seed=None):
+        """A random point on a LinearEntity.
+
+        Returns
+        =======
+
+        point : Point
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line, Ray, Segment
+        >>> p1, p2 = Point(0, 0), Point(5, 3)
+        >>> line = Line(p1, p2)
+        >>> r = line.random_point(seed=42)  # seed value is optional
+        >>> r.n(3)
+        Point2D(-0.72, -0.432)
+        >>> r in line
+        True
+        >>> Ray(p1, p2).random_point(seed=42).n(3)
+        Point2D(0.72, 0.432)
+        >>> Segment(p1, p2).random_point(seed=42).n(3)
+        Point2D(3.2, 1.92)
+
+        """
+        if seed is not None:
+            rng = random.Random(seed)
+        else:
+            rng = random
+        pt = self.arbitrary_point(t)
+        if isinstance(self, Ray):
+            v = abs(rng.gauss(0, 1))
+        elif isinstance(self, Segment):
+            v = rng.random()
+        elif isinstance(self, Line):
+            v = rng.gauss(0, 1)
+        else:
+            raise NotImplementedError('unhandled line type')
+        return pt.subs(t, Rational(v))
+
+    def bisectors(self, other):
+        """Returns the perpendicular lines which pass through the intersections
+        of self and other that are in the same plane.
+
+        Parameters
+        ==========
+
+        line : Line3D
+
+        Returns
+        =======
+
+        list: two Line instances
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D, Line3D
+        >>> r1 = Line3D(Point3D(0, 0, 0), Point3D(1, 0, 0))
+        >>> r2 = Line3D(Point3D(0, 0, 0), Point3D(0, 1, 0))
+        >>> r1.bisectors(r2)
+        [Line3D(Point3D(0, 0, 0), Point3D(1, 1, 0)), Line3D(Point3D(0, 0, 0), Point3D(1, -1, 0))]
+
+        """
+        if not isinstance(other, LinearEntity):
+            raise GeometryError("Expecting LinearEntity, not %s" % other)
+
+        l1, l2 = self, other
+
+        # make sure dimensions match or else a warning will rise from
+        # intersection calculation
+        if l1.p1.ambient_dimension != l2.p1.ambient_dimension:
+            if isinstance(l1, Line2D):
+                l1, l2 = l2, l1
+            _, p1 = Point._normalize_dimension(l1.p1, l2.p1, on_morph='ignore')
+            _, p2 = Point._normalize_dimension(l1.p2, l2.p2, on_morph='ignore')
+            l2 = Line(p1, p2)
+
+        point = intersection(l1, l2)
+
+        # Three cases: Lines may intersect in a point, may be equal or may not intersect.
+        if not point:
+            raise GeometryError("The lines do not intersect")
+        else:
+            pt = point[0]
+            if isinstance(pt, Line):
+                # Intersection is a line because both lines are coincident
+                return [self]
+
+
+        d1 = l1.direction.unit
+        d2 = l2.direction.unit
+
+        bis1 = Line(pt, pt + d1 + d2)
+        bis2 = Line(pt, pt + d1 - d2)
+
+        return [bis1, bis2]
+
+
+class Line(LinearEntity):
+    """An infinite line in space.
+
+    A 2D line is declared with two distinct points, point and slope, or
+    an equation. A 3D line may be defined with a point and a direction ratio.
+
+    Parameters
+    ==========
+
+    p1 : Point
+    p2 : Point
+    slope : SymPy expression
+    direction_ratio : list
+    equation : equation of a line
+
+    Notes
+    =====
+
+    `Line` will automatically subclass to `Line2D` or `Line3D` based
+    on the dimension of `p1`.  The `slope` argument is only relevant
+    for `Line2D` and the `direction_ratio` argument is only relevant
+    for `Line3D`.
+
+    The order of the points will define the direction of the line
+    which is used when calculating the angle between lines.
+
+    See Also
+    ========
+
+    sympy.geometry.point.Point
+    sympy.geometry.line.Line2D
+    sympy.geometry.line.Line3D
+
+    Examples
+    ========
+
+    >>> from sympy import Line, Segment, Point, Eq
+    >>> from sympy.abc import x, y, a, b
+
+    >>> L = Line(Point(2,3), Point(3,5))
+    >>> L
+    Line2D(Point2D(2, 3), Point2D(3, 5))
+    >>> L.points
+    (Point2D(2, 3), Point2D(3, 5))
+    >>> L.equation()
+    -2*x + y + 1
+    >>> L.coefficients
+    (-2, 1, 1)
+
+    Instantiate with keyword ``slope``:
+
+    >>> Line(Point(0, 0), slope=0)
+    Line2D(Point2D(0, 0), Point2D(1, 0))
+
+    Instantiate with another linear object
+
+    >>> s = Segment((0, 0), (0, 1))
+    >>> Line(s).equation()
+    x
+
+    The line corresponding to an equation in the for `ax + by + c = 0`,
+    can be entered:
+
+    >>> Line(3*x + y + 18)
+    Line2D(Point2D(0, -18), Point2D(1, -21))
+
+    If `x` or `y` has a different name, then they can be specified, too,
+    as a string (to match the name) or symbol:
+
+    >>> Line(Eq(3*a + b, -18), x='a', y=b)
+    Line2D(Point2D(0, -18), Point2D(1, -21))
+    """
+    def __new__(cls, *args, **kwargs):
+        if len(args) == 1 and isinstance(args[0], (Expr, Eq)):
+            missing = uniquely_named_symbol('?', args)
+            if not kwargs:
+                x = 'x'
+                y = 'y'
+            else:
+                x = kwargs.pop('x', missing)
+                y = kwargs.pop('y', missing)
+            if kwargs:
+                raise ValueError('expecting only x and y as keywords')
+
+            equation = args[0]
+            if isinstance(equation, Eq):
+                equation = equation.lhs - equation.rhs
+
+            def find_or_missing(x):
+                try:
+                    return find(x, equation)
+                except ValueError:
+                    return missing
+            x = find_or_missing(x)
+            y = find_or_missing(y)
+
+            a, b, c = linear_coeffs(equation, x, y)
+
+            if b:
+                return Line((0, -c/b), slope=-a/b)
+            if a:
+                return Line((-c/a, 0), slope=oo)
+
+            raise ValueError('not found in equation: %s' % (set('xy') - {x, y}))
+
+        else:
+            if len(args) > 0:
+                p1 = args[0]
+                if len(args) > 1:
+                    p2 = args[1]
+                else:
+                    p2 = None
+
+                if isinstance(p1, LinearEntity):
+                    if p2:
+                        raise ValueError('If p1 is a LinearEntity, p2 must be None.')
+                    dim = len(p1.p1)
+                else:
+                    p1 = Point(p1)
+                    dim = len(p1)
+                    if p2 is not None or isinstance(p2, Point) and p2.ambient_dimension != dim:
+                        p2 = Point(p2)
+
+                if dim == 2:
+                    return Line2D(p1, p2, **kwargs)
+                elif dim == 3:
+                    return Line3D(p1, p2, **kwargs)
+                return LinearEntity.__new__(cls, p1, p2, **kwargs)
+
+    def contains(self, other):
+        """
+        Return True if `other` is on this Line, or False otherwise.
+
+        Examples
+        ========
+
+        >>> from sympy import Line,Point
+        >>> p1, p2 = Point(0, 1), Point(3, 4)
+        >>> l = Line(p1, p2)
+        >>> l.contains(p1)
+        True
+        >>> l.contains((0, 1))
+        True
+        >>> l.contains((0, 0))
+        False
+        >>> a = (0, 0, 0)
+        >>> b = (1, 1, 1)
+        >>> c = (2, 2, 2)
+        >>> l1 = Line(a, b)
+        >>> l2 = Line(b, a)
+        >>> l1 == l2
+        False
+        >>> l1 in l2
+        True
+
+        """
+        if not isinstance(other, GeometryEntity):
+            other = Point(other, dim=self.ambient_dimension)
+        if isinstance(other, Point):
+            return Point.is_collinear(other, self.p1, self.p2)
+        if isinstance(other, LinearEntity):
+            return Point.is_collinear(self.p1, self.p2, other.p1, other.p2)
+        return False
+
+    def distance(self, other):
+        """
+        Finds the shortest distance between a line and a point.
+
+        Raises
+        ======
+
+        NotImplementedError is raised if `other` is not a Point
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2 = Point(0, 0), Point(1, 1)
+        >>> s = Line(p1, p2)
+        >>> s.distance(Point(-1, 1))
+        sqrt(2)
+        >>> s.distance((-1, 2))
+        3*sqrt(2)/2
+        >>> p1, p2 = Point(0, 0, 0), Point(1, 1, 1)
+        >>> s = Line(p1, p2)
+        >>> s.distance(Point(-1, 1, 1))
+        2*sqrt(6)/3
+        >>> s.distance((-1, 1, 1))
+        2*sqrt(6)/3
+
+        """
+        if not isinstance(other, GeometryEntity):
+            other = Point(other, dim=self.ambient_dimension)
+        if self.contains(other):
+            return S.Zero
+        return self.perpendicular_segment(other).length
+
+    def equals(self, other):
+        """Returns True if self and other are the same mathematical entities"""
+        if not isinstance(other, Line):
+            return False
+        return Point.is_collinear(self.p1, other.p1, self.p2, other.p2)
+
+    def plot_interval(self, parameter='t'):
+        """The plot interval for the default geometric plot of line. Gives
+        values that will produce a line that is +/- 5 units long (where a
+        unit is the distance between the two points that define the line).
+
+        Parameters
+        ==========
+
+        parameter : str, optional
+            Default value is 't'.
+
+        Returns
+        =======
+
+        plot_interval : list (plot interval)
+            [parameter, lower_bound, upper_bound]
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2 = Point(0, 0), Point(5, 3)
+        >>> l1 = Line(p1, p2)
+        >>> l1.plot_interval()
+        [t, -5, 5]
+
+        """
+        t = _symbol(parameter, real=True)
+        return [t, -5, 5]
+
+
+class Ray(LinearEntity):
+    """A Ray is a semi-line in the space with a source point and a direction.
+
+    Parameters
+    ==========
+
+    p1 : Point
+        The source of the Ray
+    p2 : Point or radian value
+        This point determines the direction in which the Ray propagates.
+        If given as an angle it is interpreted in radians with the positive
+        direction being ccw.
+
+    Attributes
+    ==========
+
+    source
+
+    See Also
+    ========
+
+    sympy.geometry.line.Ray2D
+    sympy.geometry.line.Ray3D
+    sympy.geometry.point.Point
+    sympy.geometry.line.Line
+
+    Notes
+    =====
+
+    `Ray` will automatically subclass to `Ray2D` or `Ray3D` based on the
+    dimension of `p1`.
+
+    Examples
+    ========
+
+    >>> from sympy import Ray, Point, pi
+    >>> r = Ray(Point(2, 3), Point(3, 5))
+    >>> r
+    Ray2D(Point2D(2, 3), Point2D(3, 5))
+    >>> r.points
+    (Point2D(2, 3), Point2D(3, 5))
+    >>> r.source
+    Point2D(2, 3)
+    >>> r.xdirection
+    oo
+    >>> r.ydirection
+    oo
+    >>> r.slope
+    2
+    >>> Ray(Point(0, 0), angle=pi/4).slope
+    1
+
+    """
+    def __new__(cls, p1, p2=None, **kwargs):
+        p1 = Point(p1)
+        if p2 is not None:
+            p1, p2 = Point._normalize_dimension(p1, Point(p2))
+        dim = len(p1)
+
+        if dim == 2:
+            return Ray2D(p1, p2, **kwargs)
+        elif dim == 3:
+            return Ray3D(p1, p2, **kwargs)
+        return LinearEntity.__new__(cls, p1, p2, **kwargs)
+
+    def _svg(self, scale_factor=1., fill_color="#66cc99"):
+        """Returns SVG path element for the LinearEntity.
+
+        Parameters
+        ==========
+
+        scale_factor : float
+            Multiplication factor for the SVG stroke-width.  Default is 1.
+        fill_color : str, optional
+            Hex string for fill color. Default is "#66cc99".
+        """
+        verts = (N(self.p1), N(self.p2))
+        coords = ["{},{}".format(p.x, p.y) for p in verts]
+        path = "M {} L {}".format(coords[0], " L ".join(coords[1:]))
+
+        return (
+            '<path fill-rule="evenodd" fill="{2}" stroke="#555555" '
+            'stroke-width="{0}" opacity="0.6" d="{1}" '
+            'marker-start="url(#markerCircle)" marker-end="url(#markerArrow)"/>'
+        ).format(2.*scale_factor, path, fill_color)
+
+    def contains(self, other):
+        """
+        Is other GeometryEntity contained in this Ray?
+
+        Examples
+        ========
+
+        >>> from sympy import Ray,Point,Segment
+        >>> p1, p2 = Point(0, 0), Point(4, 4)
+        >>> r = Ray(p1, p2)
+        >>> r.contains(p1)
+        True
+        >>> r.contains((1, 1))
+        True
+        >>> r.contains((1, 3))
+        False
+        >>> s = Segment((1, 1), (2, 2))
+        >>> r.contains(s)
+        True
+        >>> s = Segment((1, 2), (2, 5))
+        >>> r.contains(s)
+        False
+        >>> r1 = Ray((2, 2), (3, 3))
+        >>> r.contains(r1)
+        True
+        >>> r1 = Ray((2, 2), (3, 5))
+        >>> r.contains(r1)
+        False
+        """
+        if not isinstance(other, GeometryEntity):
+            other = Point(other, dim=self.ambient_dimension)
+        if isinstance(other, Point):
+            if Point.is_collinear(self.p1, self.p2, other):
+                # if we're in the direction of the ray, our
+                # direction vector dot the ray's direction vector
+                # should be non-negative
+                return bool((self.p2 - self.p1).dot(other - self.p1) >= S.Zero)
+            return False
+        elif isinstance(other, Ray):
+            if Point.is_collinear(self.p1, self.p2, other.p1, other.p2):
+                return bool((self.p2 - self.p1).dot(other.p2 - other.p1) > S.Zero)
+            return False
+        elif isinstance(other, Segment):
+            return other.p1 in self and other.p2 in self
+
+        # No other known entity can be contained in a Ray
+        return False
+
+    def distance(self, other):
+        """
+        Finds the shortest distance between the ray and a point.
+
+        Raises
+        ======
+
+        NotImplementedError is raised if `other` is not a Point
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ray
+        >>> p1, p2 = Point(0, 0), Point(1, 1)
+        >>> s = Ray(p1, p2)
+        >>> s.distance(Point(-1, -1))
+        sqrt(2)
+        >>> s.distance((-1, 2))
+        3*sqrt(2)/2
+        >>> p1, p2 = Point(0, 0, 0), Point(1, 1, 2)
+        >>> s = Ray(p1, p2)
+        >>> s
+        Ray3D(Point3D(0, 0, 0), Point3D(1, 1, 2))
+        >>> s.distance(Point(-1, -1, 2))
+        4*sqrt(3)/3
+        >>> s.distance((-1, -1, 2))
+        4*sqrt(3)/3
+
+        """
+        if not isinstance(other, GeometryEntity):
+            other = Point(other, dim=self.ambient_dimension)
+        if self.contains(other):
+            return S.Zero
+
+        proj = Line(self.p1, self.p2).projection(other)
+        if self.contains(proj):
+            return abs(other - proj)
+        else:
+            return abs(other - self.source)
+
+    def equals(self, other):
+        """Returns True if self and other are the same mathematical entities"""
+        if not isinstance(other, Ray):
+            return False
+        return self.source == other.source and other.p2 in self
+
+    def plot_interval(self, parameter='t'):
+        """The plot interval for the default geometric plot of the Ray. Gives
+        values that will produce a ray that is 10 units long (where a unit is
+        the distance between the two points that define the ray).
+
+        Parameters
+        ==========
+
+        parameter : str, optional
+            Default value is 't'.
+
+        Returns
+        =======
+
+        plot_interval : list
+            [parameter, lower_bound, upper_bound]
+
+        Examples
+        ========
+
+        >>> from sympy import Ray, pi
+        >>> r = Ray((0, 0), angle=pi/4)
+        >>> r.plot_interval()
+        [t, 0, 10]
+
+        """
+        t = _symbol(parameter, real=True)
+        return [t, 0, 10]
+
+    @property
+    def source(self):
+        """The point from which the ray emanates.
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ray
+        >>> p1, p2 = Point(0, 0), Point(4, 1)
+        >>> r1 = Ray(p1, p2)
+        >>> r1.source
+        Point2D(0, 0)
+        >>> p1, p2 = Point(0, 0, 0), Point(4, 1, 5)
+        >>> r1 = Ray(p2, p1)
+        >>> r1.source
+        Point3D(4, 1, 5)
+
+        """
+        return self.p1
+
+
+class Segment(LinearEntity):
+    """A line segment in space.
+
+    Parameters
+    ==========
+
+    p1 : Point
+    p2 : Point
+
+    Attributes
+    ==========
+
+    length : number or SymPy expression
+    midpoint : Point
+
+    See Also
+    ========
+
+    sympy.geometry.line.Segment2D
+    sympy.geometry.line.Segment3D
+    sympy.geometry.point.Point
+    sympy.geometry.line.Line
+
+    Notes
+    =====
+
+    If 2D or 3D points are used to define `Segment`, it will
+    be automatically subclassed to `Segment2D` or `Segment3D`.
+
+    Examples
+    ========
+
+    >>> from sympy import Point, Segment
+    >>> Segment((1, 0), (1, 1)) # tuples are interpreted as pts
+    Segment2D(Point2D(1, 0), Point2D(1, 1))
+    >>> s = Segment(Point(4, 3), Point(1, 1))
+    >>> s.points
+    (Point2D(4, 3), Point2D(1, 1))
+    >>> s.slope
+    2/3
+    >>> s.length
+    sqrt(13)
+    >>> s.midpoint
+    Point2D(5/2, 2)
+    >>> Segment((1, 0, 0), (1, 1, 1)) # tuples are interpreted as pts
+    Segment3D(Point3D(1, 0, 0), Point3D(1, 1, 1))
+    >>> s = Segment(Point(4, 3, 9), Point(1, 1, 7)); s
+    Segment3D(Point3D(4, 3, 9), Point3D(1, 1, 7))
+    >>> s.points
+    (Point3D(4, 3, 9), Point3D(1, 1, 7))
+    >>> s.length
+    sqrt(17)
+    >>> s.midpoint
+    Point3D(5/2, 2, 8)
+
+    """
+    def __new__(cls, p1, p2, **kwargs):
+        p1, p2 = Point._normalize_dimension(Point(p1), Point(p2))
+        dim = len(p1)
+
+        if dim == 2:
+            return Segment2D(p1, p2, **kwargs)
+        elif dim == 3:
+            return Segment3D(p1, p2, **kwargs)
+        return LinearEntity.__new__(cls, p1, p2, **kwargs)
+
+    def contains(self, other):
+        """
+        Is the other GeometryEntity contained within this Segment?
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Segment
+        >>> p1, p2 = Point(0, 1), Point(3, 4)
+        >>> s = Segment(p1, p2)
+        >>> s2 = Segment(p2, p1)
+        >>> s.contains(s2)
+        True
+        >>> from sympy import Point3D, Segment3D
+        >>> p1, p2 = Point3D(0, 1, 1), Point3D(3, 4, 5)
+        >>> s = Segment3D(p1, p2)
+        >>> s2 = Segment3D(p2, p1)
+        >>> s.contains(s2)
+        True
+        >>> s.contains((p1 + p2)/2)
+        True
+        """
+        if not isinstance(other, GeometryEntity):
+            other = Point(other, dim=self.ambient_dimension)
+        if isinstance(other, Point):
+            if Point.is_collinear(other, self.p1, self.p2):
+                if isinstance(self, Segment2D):
+                    # if it is collinear and is in the bounding box of the
+                    # segment then it must be on the segment
+                    vert = (1/self.slope).equals(0)
+                    if vert is False:
+                        isin = (self.p1.x - other.x)*(self.p2.x - other.x) <= 0
+                        if isin in (True, False):
+                            return isin
+                    if vert is True:
+                        isin = (self.p1.y - other.y)*(self.p2.y - other.y) <= 0
+                        if isin in (True, False):
+                            return isin
+                # use the triangle inequality
+                d1, d2 = other - self.p1, other - self.p2
+                d = self.p2 - self.p1
+                # without the call to simplify, SymPy cannot tell that an expression
+                # like (a+b)*(a/2+b/2) is always non-negative.  If it cannot be
+                # determined, raise an Undecidable error
+                try:
+                    # the triangle inequality says that |d1|+|d2| >= |d| and is strict
+                    # only if other lies in the line segment
+                    return bool(simplify(Eq(abs(d1) + abs(d2) - abs(d), 0)))
+                except TypeError:
+                    raise Undecidable("Cannot determine if {} is in {}".format(other, self))
+        if isinstance(other, Segment):
+            return other.p1 in self and other.p2 in self
+
+        return False
+
+    def equals(self, other):
+        """Returns True if self and other are the same mathematical entities"""
+        return isinstance(other, self.func) and list(
+            ordered(self.args)) == list(ordered(other.args))
+
+    def distance(self, other):
+        """
+        Finds the shortest distance between a line segment and a point.
+
+        Raises
+        ======
+
+        NotImplementedError is raised if `other` is not a Point
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Segment
+        >>> p1, p2 = Point(0, 1), Point(3, 4)
+        >>> s = Segment(p1, p2)
+        >>> s.distance(Point(10, 15))
+        sqrt(170)
+        >>> s.distance((0, 12))
+        sqrt(73)
+        >>> from sympy import Point3D, Segment3D
+        >>> p1, p2 = Point3D(0, 0, 3), Point3D(1, 1, 4)
+        >>> s = Segment3D(p1, p2)
+        >>> s.distance(Point3D(10, 15, 12))
+        sqrt(341)
+        >>> s.distance((10, 15, 12))
+        sqrt(341)
+        """
+        if not isinstance(other, GeometryEntity):
+            other = Point(other, dim=self.ambient_dimension)
+        if isinstance(other, Point):
+            vp1 = other - self.p1
+            vp2 = other - self.p2
+
+            dot_prod_sign_1 = self.direction.dot(vp1) >= 0
+            dot_prod_sign_2 = self.direction.dot(vp2) <= 0
+            if dot_prod_sign_1 and dot_prod_sign_2:
+                return Line(self.p1, self.p2).distance(other)
+            if dot_prod_sign_1 and not dot_prod_sign_2:
+                return abs(vp2)
+            if not dot_prod_sign_1 and dot_prod_sign_2:
+                return abs(vp1)
+        raise NotImplementedError()
+
+    @property
+    def length(self):
+        """The length of the line segment.
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point.distance
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Segment
+        >>> p1, p2 = Point(0, 0), Point(4, 3)
+        >>> s1 = Segment(p1, p2)
+        >>> s1.length
+        5
+        >>> from sympy import Point3D, Segment3D
+        >>> p1, p2 = Point3D(0, 0, 0), Point3D(4, 3, 3)
+        >>> s1 = Segment3D(p1, p2)
+        >>> s1.length
+        sqrt(34)
+
+        """
+        return Point.distance(self.p1, self.p2)
+
+    @property
+    def midpoint(self):
+        """The midpoint of the line segment.
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point.midpoint
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Segment
+        >>> p1, p2 = Point(0, 0), Point(4, 3)
+        >>> s1 = Segment(p1, p2)
+        >>> s1.midpoint
+        Point2D(2, 3/2)
+        >>> from sympy import Point3D, Segment3D
+        >>> p1, p2 = Point3D(0, 0, 0), Point3D(4, 3, 3)
+        >>> s1 = Segment3D(p1, p2)
+        >>> s1.midpoint
+        Point3D(2, 3/2, 3/2)
+
+        """
+        return Point.midpoint(self.p1, self.p2)
+
+    def perpendicular_bisector(self, p=None):
+        """The perpendicular bisector of this segment.
+
+        If no point is specified or the point specified is not on the
+        bisector then the bisector is returned as a Line. Otherwise a
+        Segment is returned that joins the point specified and the
+        intersection of the bisector and the segment.
+
+        Parameters
+        ==========
+
+        p : Point
+
+        Returns
+        =======
+
+        bisector : Line or Segment
+
+        See Also
+        ========
+
+        LinearEntity.perpendicular_segment
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Segment
+        >>> p1, p2, p3 = Point(0, 0), Point(6, 6), Point(5, 1)
+        >>> s1 = Segment(p1, p2)
+        >>> s1.perpendicular_bisector()
+        Line2D(Point2D(3, 3), Point2D(-3, 9))
+
+        >>> s1.perpendicular_bisector(p3)
+        Segment2D(Point2D(5, 1), Point2D(3, 3))
+
+        """
+        l = self.perpendicular_line(self.midpoint)
+        if p is not None:
+            p2 = Point(p, dim=self.ambient_dimension)
+            if p2 in l:
+                return Segment(p2, self.midpoint)
+        return l
+
+    def plot_interval(self, parameter='t'):
+        """The plot interval for the default geometric plot of the Segment gives
+        values that will produce the full segment in a plot.
+
+        Parameters
+        ==========
+
+        parameter : str, optional
+            Default value is 't'.
+
+        Returns
+        =======
+
+        plot_interval : list
+            [parameter, lower_bound, upper_bound]
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Segment
+        >>> p1, p2 = Point(0, 0), Point(5, 3)
+        >>> s1 = Segment(p1, p2)
+        >>> s1.plot_interval()
+        [t, 0, 1]
+
+        """
+        t = _symbol(parameter, real=True)
+        return [t, 0, 1]
+
+
+class LinearEntity2D(LinearEntity):
+    """A base class for all linear entities (line, ray and segment)
+    in a 2-dimensional Euclidean space.
+
+    Attributes
+    ==========
+
+    p1
+    p2
+    coefficients
+    slope
+    points
+
+    Notes
+    =====
+
+    This is an abstract class and is not meant to be instantiated.
+
+    See Also
+    ========
+
+    sympy.geometry.entity.GeometryEntity
+
+    """
+    @property
+    def bounds(self):
+        """Return a tuple (xmin, ymin, xmax, ymax) representing the bounding
+        rectangle for the geometric figure.
+
+        """
+        verts = self.points
+        xs = [p.x for p in verts]
+        ys = [p.y for p in verts]
+        return (min(xs), min(ys), max(xs), max(ys))
+
+    def perpendicular_line(self, p):
+        """Create a new Line perpendicular to this linear entity which passes
+        through the point `p`.
+
+        Parameters
+        ==========
+
+        p : Point
+
+        Returns
+        =======
+
+        line : Line
+
+        See Also
+        ========
+
+        sympy.geometry.line.LinearEntity.is_perpendicular, perpendicular_segment
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2, p3 = Point(0, 0), Point(2, 3), Point(-2, 2)
+        >>> L = Line(p1, p2)
+        >>> P = L.perpendicular_line(p3); P
+        Line2D(Point2D(-2, 2), Point2D(-5, 4))
+        >>> L.is_perpendicular(P)
+        True
+
+        In 2D, the first point of the perpendicular line is the
+        point through which was required to pass; the second
+        point is arbitrarily chosen. To get a line that explicitly
+        uses a point in the line, create a line from the perpendicular
+        segment from the line to the point:
+
+        >>> Line(L.perpendicular_segment(p3))
+        Line2D(Point2D(-2, 2), Point2D(4/13, 6/13))
+        """
+        p = Point(p, dim=self.ambient_dimension)
+        # any two lines in R^2 intersect, so blindly making
+        # a line through p in an orthogonal direction will work
+        # and is faster than finding the projection point as in 3D
+        return Line(p, p + self.direction.orthogonal_direction)
+
+    @property
+    def slope(self):
+        """The slope of this linear entity, or infinity if vertical.
+
+        Returns
+        =======
+
+        slope : number or SymPy expression
+
+        See Also
+        ========
+
+        coefficients
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2 = Point(0, 0), Point(3, 5)
+        >>> l1 = Line(p1, p2)
+        >>> l1.slope
+        5/3
+
+        >>> p3 = Point(0, 4)
+        >>> l2 = Line(p1, p3)
+        >>> l2.slope
+        oo
+
+        """
+        d1, d2 = (self.p1 - self.p2).args
+        if d1 == 0:
+            return S.Infinity
+        return simplify(d2/d1)
+
+
+class Line2D(LinearEntity2D, Line):
+    """An infinite line in space 2D.
+
+    A line is declared with two distinct points or a point and slope
+    as defined using keyword `slope`.
+
+    Parameters
+    ==========
+
+    p1 : Point
+    pt : Point
+    slope : SymPy expression
+
+    See Also
+    ========
+
+    sympy.geometry.point.Point
+
+    Examples
+    ========
+
+    >>> from sympy import Line, Segment, Point
+    >>> L = Line(Point(2,3), Point(3,5))
+    >>> L
+    Line2D(Point2D(2, 3), Point2D(3, 5))
+    >>> L.points
+    (Point2D(2, 3), Point2D(3, 5))
+    >>> L.equation()
+    -2*x + y + 1
+    >>> L.coefficients
+    (-2, 1, 1)
+
+    Instantiate with keyword ``slope``:
+
+    >>> Line(Point(0, 0), slope=0)
+    Line2D(Point2D(0, 0), Point2D(1, 0))
+
+    Instantiate with another linear object
+
+    >>> s = Segment((0, 0), (0, 1))
+    >>> Line(s).equation()
+    x
+    """
+    def __new__(cls, p1, pt=None, slope=None, **kwargs):
+        if isinstance(p1, LinearEntity):
+            if pt is not None:
+                raise ValueError('When p1 is a LinearEntity, pt should be None')
+            p1, pt = Point._normalize_dimension(*p1.args, dim=2)
+        else:
+            p1 = Point(p1, dim=2)
+        if pt is not None and slope is None:
+            try:
+                p2 = Point(pt, dim=2)
+            except (NotImplementedError, TypeError, ValueError):
+                raise ValueError(filldedent('''
+                    The 2nd argument was not a valid Point.
+                    If it was a slope, enter it with keyword "slope".
+                    '''))
+        elif slope is not None and pt is None:
+            slope = sympify(slope)
+            if slope.is_finite is False:
+                # when infinite slope, don't change x
+                dx = 0
+                dy = 1
+            else:
+                # go over 1 up slope
+                dx = 1
+                dy = slope
+            # XXX avoiding simplification by adding to coords directly
+            p2 = Point(p1.x + dx, p1.y + dy, evaluate=False)
+        else:
+            raise ValueError('A 2nd Point or keyword "slope" must be used.')
+        return LinearEntity2D.__new__(cls, p1, p2, **kwargs)
+
+    def _svg(self, scale_factor=1., fill_color="#66cc99"):
+        """Returns SVG path element for the LinearEntity.
+
+        Parameters
+        ==========
+
+        scale_factor : float
+            Multiplication factor for the SVG stroke-width.  Default is 1.
+        fill_color : str, optional
+            Hex string for fill color. Default is "#66cc99".
+        """
+        verts = (N(self.p1), N(self.p2))
+        coords = ["{},{}".format(p.x, p.y) for p in verts]
+        path = "M {} L {}".format(coords[0], " L ".join(coords[1:]))
+
+        return (
+            '<path fill-rule="evenodd" fill="{2}" stroke="#555555" '
+            'stroke-width="{0}" opacity="0.6" d="{1}" '
+            'marker-start="url(#markerReverseArrow)" marker-end="url(#markerArrow)"/>'
+        ).format(2.*scale_factor, path, fill_color)
+
+    @property
+    def coefficients(self):
+        """The coefficients (`a`, `b`, `c`) for `ax + by + c = 0`.
+
+        See Also
+        ========
+
+        sympy.geometry.line.Line2D.equation
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> from sympy.abc import x, y
+        >>> p1, p2 = Point(0, 0), Point(5, 3)
+        >>> l = Line(p1, p2)
+        >>> l.coefficients
+        (-3, 5, 0)
+
+        >>> p3 = Point(x, y)
+        >>> l2 = Line(p1, p3)
+        >>> l2.coefficients
+        (-y, x, 0)
+
+        """
+        p1, p2 = self.points
+        if p1.x == p2.x:
+            return (S.One, S.Zero, -p1.x)
+        elif p1.y == p2.y:
+            return (S.Zero, S.One, -p1.y)
+        return tuple([simplify(i) for i in
+                      (self.p1.y - self.p2.y,
+                       self.p2.x - self.p1.x,
+                       self.p1.x*self.p2.y - self.p1.y*self.p2.x)])
+
+    def equation(self, x='x', y='y'):
+        """The equation of the line: ax + by + c.
+
+        Parameters
+        ==========
+
+        x : str, optional
+            The name to use for the x-axis, default value is 'x'.
+        y : str, optional
+            The name to use for the y-axis, default value is 'y'.
+
+        Returns
+        =======
+
+        equation : SymPy expression
+
+        See Also
+        ========
+
+        sympy.geometry.line.Line2D.coefficients
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2 = Point(1, 0), Point(5, 3)
+        >>> l1 = Line(p1, p2)
+        >>> l1.equation()
+        -3*x + 4*y + 3
+
+        """
+        x = _symbol(x, real=True)
+        y = _symbol(y, real=True)
+        p1, p2 = self.points
+        if p1.x == p2.x:
+            return x - p1.x
+        elif p1.y == p2.y:
+            return y - p1.y
+
+        a, b, c = self.coefficients
+        return a*x + b*y + c
+
+
+class Ray2D(LinearEntity2D, Ray):
+    """
+    A Ray is a semi-line in the space with a source point and a direction.
+
+    Parameters
+    ==========
+
+    p1 : Point
+        The source of the Ray
+    p2 : Point or radian value
+        This point determines the direction in which the Ray propagates.
+        If given as an angle it is interpreted in radians with the positive
+        direction being ccw.
+
+    Attributes
+    ==========
+
+    source
+    xdirection
+    ydirection
+
+    See Also
+    ========
+
+    sympy.geometry.point.Point, Line
+
+    Examples
+    ========
+
+    >>> from sympy import Point, pi, Ray
+    >>> r = Ray(Point(2, 3), Point(3, 5))
+    >>> r
+    Ray2D(Point2D(2, 3), Point2D(3, 5))
+    >>> r.points
+    (Point2D(2, 3), Point2D(3, 5))
+    >>> r.source
+    Point2D(2, 3)
+    >>> r.xdirection
+    oo
+    >>> r.ydirection
+    oo
+    >>> r.slope
+    2
+    >>> Ray(Point(0, 0), angle=pi/4).slope
+    1
+
+    """
+    def __new__(cls, p1, pt=None, angle=None, **kwargs):
+        p1 = Point(p1, dim=2)
+        if pt is not None and angle is None:
+            try:
+                p2 = Point(pt, dim=2)
+            except (NotImplementedError, TypeError, ValueError):
+                raise ValueError(filldedent('''
+                    The 2nd argument was not a valid Point; if
+                    it was meant to be an angle it should be
+                    given with keyword "angle".'''))
+            if p1 == p2:
+                raise ValueError('A Ray requires two distinct points.')
+        elif angle is not None and pt is None:
+            # we need to know if the angle is an odd multiple of pi/2
+            angle = sympify(angle)
+            c = _pi_coeff(angle)
+            p2 = None
+            if c is not None:
+                if c.is_Rational:
+                    if c.q == 2:
+                        if c.p == 1:
+                            p2 = p1 + Point(0, 1)
+                        elif c.p == 3:
+                            p2 = p1 + Point(0, -1)
+                    elif c.q == 1:
+                        if c.p == 0:
+                            p2 = p1 + Point(1, 0)
+                        elif c.p == 1:
+                            p2 = p1 + Point(-1, 0)
+                if p2 is None:
+                    c *= S.Pi
+            else:
+                c = angle % (2*S.Pi)
+            if not p2:
+                m = 2*c/S.Pi
+                left = And(1 < m, m < 3)  # is it in quadrant 2 or 3?
+                x = Piecewise((-1, left), (Piecewise((0, Eq(m % 1, 0)), (1, True)), True))
+                y = Piecewise((-tan(c), left), (Piecewise((1, Eq(m, 1)), (-1, Eq(m, 3)), (tan(c), True)), True))
+                p2 = p1 + Point(x, y)
+        else:
+            raise ValueError('A 2nd point or keyword "angle" must be used.')
+
+        return LinearEntity2D.__new__(cls, p1, p2, **kwargs)
+
+    @property
+    def xdirection(self):
+        """The x direction of the ray.
+
+        Positive infinity if the ray points in the positive x direction,
+        negative infinity if the ray points in the negative x direction,
+        or 0 if the ray is vertical.
+
+        See Also
+        ========
+
+        ydirection
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ray
+        >>> p1, p2, p3 = Point(0, 0), Point(1, 1), Point(0, -1)
+        >>> r1, r2 = Ray(p1, p2), Ray(p1, p3)
+        >>> r1.xdirection
+        oo
+        >>> r2.xdirection
+        0
+
+        """
+        if self.p1.x < self.p2.x:
+            return S.Infinity
+        elif self.p1.x == self.p2.x:
+            return S.Zero
+        else:
+            return S.NegativeInfinity
+
+    @property
+    def ydirection(self):
+        """The y direction of the ray.
+
+        Positive infinity if the ray points in the positive y direction,
+        negative infinity if the ray points in the negative y direction,
+        or 0 if the ray is horizontal.
+
+        See Also
+        ========
+
+        xdirection
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Ray
+        >>> p1, p2, p3 = Point(0, 0), Point(-1, -1), Point(-1, 0)
+        >>> r1, r2 = Ray(p1, p2), Ray(p1, p3)
+        >>> r1.ydirection
+        -oo
+        >>> r2.ydirection
+        0
+
+        """
+        if self.p1.y < self.p2.y:
+            return S.Infinity
+        elif self.p1.y == self.p2.y:
+            return S.Zero
+        else:
+            return S.NegativeInfinity
+
+    def closing_angle(r1, r2):
+        """Return the angle by which r2 must be rotated so it faces the same
+        direction as r1.
+
+        Parameters
+        ==========
+
+        r1 : Ray2D
+        r2 : Ray2D
+
+        Returns
+        =======
+
+        angle : angle in radians (ccw angle is positive)
+
+        See Also
+        ========
+
+        LinearEntity.angle_between
+
+        Examples
+        ========
+
+        >>> from sympy import Ray, pi
+        >>> r1 = Ray((0, 0), (1, 0))
+        >>> r2 = r1.rotate(-pi/2)
+        >>> angle = r1.closing_angle(r2); angle
+        pi/2
+        >>> r2.rotate(angle).direction.unit == r1.direction.unit
+        True
+        >>> r2.closing_angle(r1)
+        -pi/2
+        """
+        if not all(isinstance(r, Ray2D) for r in (r1, r2)):
+            # although the direction property is defined for
+            # all linear entities, only the Ray is truly a
+            # directed object
+            raise TypeError('Both arguments must be Ray2D objects.')
+
+        a1 = atan2(*list(reversed(r1.direction.args)))
+        a2 = atan2(*list(reversed(r2.direction.args)))
+        if a1*a2 < 0:
+            a1 = 2*S.Pi + a1 if a1 < 0 else a1
+            a2 = 2*S.Pi + a2 if a2 < 0 else a2
+        return a1 - a2
+
+
+class Segment2D(LinearEntity2D, Segment):
+    """A line segment in 2D space.
+
+    Parameters
+    ==========
+
+    p1 : Point
+    p2 : Point
+
+    Attributes
+    ==========
+
+    length : number or SymPy expression
+    midpoint : Point
+
+    See Also
+    ========
+
+    sympy.geometry.point.Point, Line
+
+    Examples
+    ========
+
+    >>> from sympy import Point, Segment
+    >>> Segment((1, 0), (1, 1)) # tuples are interpreted as pts
+    Segment2D(Point2D(1, 0), Point2D(1, 1))
+    >>> s = Segment(Point(4, 3), Point(1, 1)); s
+    Segment2D(Point2D(4, 3), Point2D(1, 1))
+    >>> s.points
+    (Point2D(4, 3), Point2D(1, 1))
+    >>> s.slope
+    2/3
+    >>> s.length
+    sqrt(13)
+    >>> s.midpoint
+    Point2D(5/2, 2)
+
+    """
+    def __new__(cls, p1, p2, **kwargs):
+        p1 = Point(p1, dim=2)
+        p2 = Point(p2, dim=2)
+
+        if p1 == p2:
+            return p1
+
+        return LinearEntity2D.__new__(cls, p1, p2, **kwargs)
+
+    def _svg(self, scale_factor=1., fill_color="#66cc99"):
+        """Returns SVG path element for the LinearEntity.
+
+        Parameters
+        ==========
+
+        scale_factor : float
+            Multiplication factor for the SVG stroke-width.  Default is 1.
+        fill_color : str, optional
+            Hex string for fill color. Default is "#66cc99".
+        """
+        verts = (N(self.p1), N(self.p2))
+        coords = ["{},{}".format(p.x, p.y) for p in verts]
+        path = "M {} L {}".format(coords[0], " L ".join(coords[1:]))
+        return (
+            '<path fill-rule="evenodd" fill="{2}" stroke="#555555" '
+            'stroke-width="{0}" opacity="0.6" d="{1}" />'
+        ).format(2.*scale_factor, path, fill_color)
+
+
+class LinearEntity3D(LinearEntity):
+    """An base class for all linear entities (line, ray and segment)
+    in a 3-dimensional Euclidean space.
+
+    Attributes
+    ==========
+
+    p1
+    p2
+    direction_ratio
+    direction_cosine
+    points
+
+    Notes
+    =====
+
+    This is a base class and is not meant to be instantiated.
+    """
+    def __new__(cls, p1, p2, **kwargs):
+        p1 = Point3D(p1, dim=3)
+        p2 = Point3D(p2, dim=3)
+        if p1 == p2:
+            # if it makes sense to return a Point, handle in subclass
+            raise ValueError(
+                "%s.__new__ requires two unique Points." % cls.__name__)
+
+        return GeometryEntity.__new__(cls, p1, p2, **kwargs)
+
+    ambient_dimension = 3
+
+    @property
+    def direction_ratio(self):
+        """The direction ratio of a given line in 3D.
+
+        See Also
+        ========
+
+        sympy.geometry.line.Line3D.equation
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D, Line3D
+        >>> p1, p2 = Point3D(0, 0, 0), Point3D(5, 3, 1)
+        >>> l = Line3D(p1, p2)
+        >>> l.direction_ratio
+        [5, 3, 1]
+        """
+        p1, p2 = self.points
+        return p1.direction_ratio(p2)
+
+    @property
+    def direction_cosine(self):
+        """The normalized direction ratio of a given line in 3D.
+
+        See Also
+        ========
+
+        sympy.geometry.line.Line3D.equation
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D, Line3D
+        >>> p1, p2 = Point3D(0, 0, 0), Point3D(5, 3, 1)
+        >>> l = Line3D(p1, p2)
+        >>> l.direction_cosine
+        [sqrt(35)/7, 3*sqrt(35)/35, sqrt(35)/35]
+        >>> sum(i**2 for i in _)
+        1
+        """
+        p1, p2 = self.points
+        return p1.direction_cosine(p2)
+
+
+class Line3D(LinearEntity3D, Line):
+    """An infinite 3D line in space.
+
+    A line is declared with two distinct points or a point and direction_ratio
+    as defined using keyword `direction_ratio`.
+
+    Parameters
+    ==========
+
+    p1 : Point3D
+    pt : Point3D
+    direction_ratio : list
+
+    See Also
+    ========
+
+    sympy.geometry.point.Point3D
+    sympy.geometry.line.Line
+    sympy.geometry.line.Line2D
+
+    Examples
+    ========
+
+    >>> from sympy import Line3D, Point3D
+    >>> L = Line3D(Point3D(2, 3, 4), Point3D(3, 5, 1))
+    >>> L
+    Line3D(Point3D(2, 3, 4), Point3D(3, 5, 1))
+    >>> L.points
+    (Point3D(2, 3, 4), Point3D(3, 5, 1))
+    """
+    def __new__(cls, p1, pt=None, direction_ratio=(), **kwargs):
+        if isinstance(p1, LinearEntity3D):
+            if pt is not None:
+                raise ValueError('if p1 is a LinearEntity, pt must be None.')
+            p1, pt = p1.args
+        else:
+            p1 = Point(p1, dim=3)
+        if pt is not None and len(direction_ratio) == 0:
+            pt = Point(pt, dim=3)
+        elif len(direction_ratio) == 3 and pt is None:
+            pt = Point3D(p1.x + direction_ratio[0], p1.y + direction_ratio[1],
+                         p1.z + direction_ratio[2])
+        else:
+            raise ValueError('A 2nd Point or keyword "direction_ratio" must '
+                             'be used.')
+
+        return LinearEntity3D.__new__(cls, p1, pt, **kwargs)
+
+    def equation(self, x='x', y='y', z='z'):
+        """Return the equations that define the line in 3D.
+
+        Parameters
+        ==========
+
+        x : str, optional
+            The name to use for the x-axis, default value is 'x'.
+        y : str, optional
+            The name to use for the y-axis, default value is 'y'.
+        z : str, optional
+            The name to use for the z-axis, default value is 'z'.
+
+        Returns
+        =======
+
+        equation : Tuple of simultaneous equations
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D, Line3D, solve
+        >>> from sympy.abc import x, y, z
+        >>> p1, p2 = Point3D(1, 0, 0), Point3D(5, 3, 0)
+        >>> l1 = Line3D(p1, p2)
+        >>> eq = l1.equation(x, y, z); eq
+        (-3*x + 4*y + 3, z)
+        >>> solve(eq.subs(z, 0), (x, y, z))
+        {x: 4*y/3 + 1}
+        """
+        x, y, z, k = [_symbol(i, real=True) for i in (x, y, z, 'k')]
+        p1, p2 = self.points
+        d1, d2, d3 = p1.direction_ratio(p2)
+        x1, y1, z1 = p1
+        eqs = [-d1*k + x - x1, -d2*k + y - y1, -d3*k + z - z1]
+        # eliminate k from equations by solving first eq with k for k
+        for i, e in enumerate(eqs):
+            if e.has(k):
+                kk = solve(e, k)[0]
+                eqs.pop(i)
+                break
+        return Tuple(*[i.subs(k, kk).as_numer_denom()[0] for i in eqs])
+
+    def distance(self, other):
+        """
+        Finds the shortest distance between a line and another object.
+
+        Parameters
+        ==========
+
+        Point3D, Line3D, Plane, tuple, list
+
+        Returns
+        =======
+
+        distance
+
+        Notes
+        =====
+
+        This method accepts only 3D entities as it's parameter
+
+        Tuples and lists are converted to Point3D and therefore must be of
+        length 3, 2 or 1.
+
+        NotImplementedError is raised if `other` is not an instance of one
+        of the specified classes: Point3D, Line3D, or Plane.
+
+        Examples
+        ========
+
+        >>> from sympy.geometry import Line3D
+        >>> l1 = Line3D((0, 0, 0), (0, 0, 1))
+        >>> l2 = Line3D((0, 1, 0), (1, 1, 1))
+        >>> l1.distance(l2)
+        1
+
+        The computed distance may be symbolic, too:
+
+        >>> from sympy.abc import x, y
+        >>> l1 = Line3D((0, 0, 0), (0, 0, 1))
+        >>> l2 = Line3D((0, x, 0), (y, x, 1))
+        >>> l1.distance(l2)
+        Abs(x*y)/Abs(sqrt(y**2))
+
+        """
+
+        from .plane import Plane  # Avoid circular import
+
+        if isinstance(other, (tuple, list)):
+            try:
+                other = Point3D(other)
+            except ValueError:
+                pass
+
+        if isinstance(other, Point3D):
+            return super().distance(other)
+
+        if isinstance(other, Line3D):
+            if self == other:
+                return S.Zero
+            if self.is_parallel(other):
+                return super().distance(other.p1)
+
+            # Skew lines
+            self_direction = Matrix(self.direction_ratio)
+            other_direction = Matrix(other.direction_ratio)
+            normal = self_direction.cross(other_direction)
+            plane_through_self = Plane(p1=self.p1, normal_vector=normal)
+            return other.p1.distance(plane_through_self)
+
+        if isinstance(other, Plane):
+            return other.distance(self)
+
+        msg = f"{other} has type {type(other)}, which is unsupported"
+        raise NotImplementedError(msg)
+
+
+class Ray3D(LinearEntity3D, Ray):
+    """
+    A Ray is a semi-line in the space with a source point and a direction.
+
+    Parameters
+    ==========
+
+    p1 : Point3D
+        The source of the Ray
+    p2 : Point or a direction vector
+    direction_ratio: Determines the direction in which the Ray propagates.
+
+
+    Attributes
+    ==========
+
+    source
+    xdirection
+    ydirection
+    zdirection
+
+    See Also
+    ========
+
+    sympy.geometry.point.Point3D, Line3D
+
+
+    Examples
+    ========
+
+    >>> from sympy import Point3D, Ray3D
+    >>> r = Ray3D(Point3D(2, 3, 4), Point3D(3, 5, 0))
+    >>> r
+    Ray3D(Point3D(2, 3, 4), Point3D(3, 5, 0))
+    >>> r.points
+    (Point3D(2, 3, 4), Point3D(3, 5, 0))
+    >>> r.source
+    Point3D(2, 3, 4)
+    >>> r.xdirection
+    oo
+    >>> r.ydirection
+    oo
+    >>> r.direction_ratio
+    [1, 2, -4]
+
+    """
+    def __new__(cls, p1, pt=None, direction_ratio=(), **kwargs):
+        if isinstance(p1, LinearEntity3D):
+            if pt is not None:
+                raise ValueError('If p1 is a LinearEntity, pt must be None')
+            p1, pt = p1.args
+        else:
+            p1 = Point(p1, dim=3)
+        if pt is not None and len(direction_ratio) == 0:
+            pt = Point(pt, dim=3)
+        elif len(direction_ratio) == 3 and pt is None:
+            pt = Point3D(p1.x + direction_ratio[0], p1.y + direction_ratio[1],
+                         p1.z + direction_ratio[2])
+        else:
+            raise ValueError(filldedent('''
+                A 2nd Point or keyword "direction_ratio" must be used.
+            '''))
+
+        return LinearEntity3D.__new__(cls, p1, pt, **kwargs)
+
+    @property
+    def xdirection(self):
+        """The x direction of the ray.
+
+        Positive infinity if the ray points in the positive x direction,
+        negative infinity if the ray points in the negative x direction,
+        or 0 if the ray is vertical.
+
+        See Also
+        ========
+
+        ydirection
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D, Ray3D
+        >>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(1, 1, 1), Point3D(0, -1, 0)
+        >>> r1, r2 = Ray3D(p1, p2), Ray3D(p1, p3)
+        >>> r1.xdirection
+        oo
+        >>> r2.xdirection
+        0
+
+        """
+        if self.p1.x < self.p2.x:
+            return S.Infinity
+        elif self.p1.x == self.p2.x:
+            return S.Zero
+        else:
+            return S.NegativeInfinity
+
+    @property
+    def ydirection(self):
+        """The y direction of the ray.
+
+        Positive infinity if the ray points in the positive y direction,
+        negative infinity if the ray points in the negative y direction,
+        or 0 if the ray is horizontal.
+
+        See Also
+        ========
+
+        xdirection
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D, Ray3D
+        >>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(-1, -1, -1), Point3D(-1, 0, 0)
+        >>> r1, r2 = Ray3D(p1, p2), Ray3D(p1, p3)
+        >>> r1.ydirection
+        -oo
+        >>> r2.ydirection
+        0
+
+        """
+        if self.p1.y < self.p2.y:
+            return S.Infinity
+        elif self.p1.y == self.p2.y:
+            return S.Zero
+        else:
+            return S.NegativeInfinity
+
+    @property
+    def zdirection(self):
+        """The z direction of the ray.
+
+        Positive infinity if the ray points in the positive z direction,
+        negative infinity if the ray points in the negative z direction,
+        or 0 if the ray is horizontal.
+
+        See Also
+        ========
+
+        xdirection
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D, Ray3D
+        >>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(-1, -1, -1), Point3D(-1, 0, 0)
+        >>> r1, r2 = Ray3D(p1, p2), Ray3D(p1, p3)
+        >>> r1.ydirection
+        -oo
+        >>> r2.ydirection
+        0
+        >>> r2.zdirection
+        0
+
+        """
+        if self.p1.z < self.p2.z:
+            return S.Infinity
+        elif self.p1.z == self.p2.z:
+            return S.Zero
+        else:
+            return S.NegativeInfinity
+
+
+class Segment3D(LinearEntity3D, Segment):
+    """A line segment in a 3D space.
+
+    Parameters
+    ==========
+
+    p1 : Point3D
+    p2 : Point3D
+
+    Attributes
+    ==========
+
+    length : number or SymPy expression
+    midpoint : Point3D
+
+    See Also
+    ========
+
+    sympy.geometry.point.Point3D, Line3D
+
+    Examples
+    ========
+
+    >>> from sympy import Point3D, Segment3D
+    >>> Segment3D((1, 0, 0), (1, 1, 1)) # tuples are interpreted as pts
+    Segment3D(Point3D(1, 0, 0), Point3D(1, 1, 1))
+    >>> s = Segment3D(Point3D(4, 3, 9), Point3D(1, 1, 7)); s
+    Segment3D(Point3D(4, 3, 9), Point3D(1, 1, 7))
+    >>> s.points
+    (Point3D(4, 3, 9), Point3D(1, 1, 7))
+    >>> s.length
+    sqrt(17)
+    >>> s.midpoint
+    Point3D(5/2, 2, 8)
+
+    """
+    def __new__(cls, p1, p2, **kwargs):
+        p1 = Point(p1, dim=3)
+        p2 = Point(p2, dim=3)
+
+        if p1 == p2:
+            return p1
+
+        return LinearEntity3D.__new__(cls, p1, p2, **kwargs)

.venv/lib/python3.13/site-packages/sympy/geometry/parabola.py

@@ -0,0 +1,422 @@
+"""Parabolic geometrical entity.
+
+Contains
+* Parabola
+
+"""
+
+from sympy.core import S
+from sympy.core.sorting import ordered
+from sympy.core.symbol import _symbol, symbols
+from sympy.geometry.entity import GeometryEntity, GeometrySet
+from sympy.geometry.point import Point, Point2D
+from sympy.geometry.line import Line, Line2D, Ray2D, Segment2D, LinearEntity3D
+from sympy.geometry.ellipse import Ellipse
+from sympy.functions import sign
+from sympy.simplify.simplify import simplify
+from sympy.solvers.solvers import solve
+
+
+class Parabola(GeometrySet):
+    """A parabolic GeometryEntity.
+
+    A parabola is declared with a point, that is called 'focus', and
+    a line, that is called 'directrix'.
+    Only vertical or horizontal parabolas are currently supported.
+
+    Parameters
+    ==========
+
+    focus : Point
+        Default value is Point(0, 0)
+    directrix : Line
+
+    Attributes
+    ==========
+
+    focus
+    directrix
+    axis of symmetry
+    focal length
+    p parameter
+    vertex
+    eccentricity
+
+    Raises
+    ======
+    ValueError
+        When `focus` is not a two dimensional point.
+        When `focus` is a point of directrix.
+    NotImplementedError
+        When `directrix` is neither horizontal nor vertical.
+
+    Examples
+    ========
+
+    >>> from sympy import Parabola, Point, Line
+    >>> p1 = Parabola(Point(0, 0), Line(Point(5, 8), Point(7,8)))
+    >>> p1.focus
+    Point2D(0, 0)
+    >>> p1.directrix
+    Line2D(Point2D(5, 8), Point2D(7, 8))
+
+    """
+
+    def __new__(cls, focus=None, directrix=None, **kwargs):
+
+        if focus:
+            focus = Point(focus, dim=2)
+        else:
+            focus = Point(0, 0)
+
+        directrix = Line(directrix)
+
+        if directrix.contains(focus):
+            raise ValueError('The focus must not be a point of directrix')
+
+        return GeometryEntity.__new__(cls, focus, directrix, **kwargs)
+
+    @property
+    def ambient_dimension(self):
+        """Returns the ambient dimension of parabola.
+
+        Returns
+        =======
+
+        ambient_dimension : integer
+
+        Examples
+        ========
+
+        >>> from sympy import Parabola, Point, Line
+        >>> f1 = Point(0, 0)
+        >>> p1 = Parabola(f1, Line(Point(5, 8), Point(7, 8)))
+        >>> p1.ambient_dimension
+        2
+
+        """
+        return 2
+
+    @property
+    def axis_of_symmetry(self):
+        """Return the axis of symmetry of the parabola: a line
+        perpendicular to the directrix passing through the focus.
+
+        Returns
+        =======
+
+        axis_of_symmetry : Line
+
+        See Also
+        ========
+
+        sympy.geometry.line.Line
+
+        Examples
+        ========
+
+        >>> from sympy import Parabola, Point, Line
+        >>> p1 = Parabola(Point(0, 0), Line(Point(5, 8), Point(7, 8)))
+        >>> p1.axis_of_symmetry
+        Line2D(Point2D(0, 0), Point2D(0, 1))
+
+        """
+        return self.directrix.perpendicular_line(self.focus)
+
+    @property
+    def directrix(self):
+        """The directrix of the parabola.
+
+        Returns
+        =======
+
+        directrix : Line
+
+        See Also
+        ========
+
+        sympy.geometry.line.Line
+
+        Examples
+        ========
+
+        >>> from sympy import Parabola, Point, Line
+        >>> l1 = Line(Point(5, 8), Point(7, 8))
+        >>> p1 = Parabola(Point(0, 0), l1)
+        >>> p1.directrix
+        Line2D(Point2D(5, 8), Point2D(7, 8))
+
+        """
+        return self.args[1]
+
+    @property
+    def eccentricity(self):
+        """The eccentricity of the parabola.
+
+        Returns
+        =======
+
+        eccentricity : number
+
+        A parabola may also be characterized as a conic section with an
+        eccentricity of 1. As a consequence of this, all parabolas are
+        similar, meaning that while they can be different sizes,
+        they are all the same shape.
+
+        See Also
+        ========
+
+        https://en.wikipedia.org/wiki/Parabola
+
+
+        Examples
+        ========
+
+        >>> from sympy import Parabola, Point, Line
+        >>> p1 = Parabola(Point(0, 0), Line(Point(5, 8), Point(7, 8)))
+        >>> p1.eccentricity
+        1
+
+        Notes
+        -----
+        The eccentricity for every Parabola is 1 by definition.
+
+        """
+        return S.One
+
+    def equation(self, x='x', y='y'):
+        """The equation of the parabola.
+
+        Parameters
+        ==========
+        x : str, optional
+            Label for the x-axis. Default value is 'x'.
+        y : str, optional
+            Label for the y-axis. Default value is 'y'.
+
+        Returns
+        =======
+        equation : SymPy expression
+
+        Examples
+        ========
+
+        >>> from sympy import Parabola, Point, Line
+        >>> p1 = Parabola(Point(0, 0), Line(Point(5, 8), Point(7, 8)))
+        >>> p1.equation()
+        -x**2 - 16*y + 64
+        >>> p1.equation('f')
+        -f**2 - 16*y + 64
+        >>> p1.equation(y='z')
+        -x**2 - 16*z + 64
+
+        """
+        x = _symbol(x, real=True)
+        y = _symbol(y, real=True)
+
+        m = self.directrix.slope
+        if m is S.Infinity:
+            t1 = 4 * (self.p_parameter) * (x - self.vertex.x)
+            t2 = (y - self.vertex.y)**2
+        elif m == 0:
+            t1 = 4 * (self.p_parameter) * (y - self.vertex.y)
+            t2 = (x - self.vertex.x)**2
+        else:
+            a, b = self.focus
+            c, d = self.directrix.coefficients[:2]
+            t1 = (x - a)**2 + (y - b)**2
+            t2 = self.directrix.equation(x, y)**2/(c**2 + d**2)
+        return t1 - t2
+
+    @property
+    def focal_length(self):
+        """The focal length of the parabola.
+
+        Returns
+        =======
+
+        focal_lenght : number or symbolic expression
+
+        Notes
+        =====
+
+        The distance between the vertex and the focus
+        (or the vertex and directrix), measured along the axis
+        of symmetry, is the "focal length".
+
+        See Also
+        ========
+
+        https://en.wikipedia.org/wiki/Parabola
+
+        Examples
+        ========
+
+        >>> from sympy import Parabola, Point, Line
+        >>> p1 = Parabola(Point(0, 0), Line(Point(5, 8), Point(7, 8)))
+        >>> p1.focal_length
+        4
+
+        """
+        distance = self.directrix.distance(self.focus)
+        focal_length = distance/2
+
+        return focal_length
+
+    @property
+    def focus(self):
+        """The focus of the parabola.
+
+        Returns
+        =======
+
+        focus : Point
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point
+
+        Examples
+        ========
+
+        >>> from sympy import Parabola, Point, Line
+        >>> f1 = Point(0, 0)
+        >>> p1 = Parabola(f1, Line(Point(5, 8), Point(7, 8)))
+        >>> p1.focus
+        Point2D(0, 0)
+
+        """
+        return self.args[0]
+
+    def intersection(self, o):
+        """The intersection of the parabola and another geometrical entity `o`.
+
+        Parameters
+        ==========
+
+        o : GeometryEntity, LinearEntity
+
+        Returns
+        =======
+
+        intersection : list of GeometryEntity objects
+
+        Examples
+        ========
+
+        >>> from sympy import Parabola, Point, Ellipse, Line, Segment
+        >>> p1 = Point(0,0)
+        >>> l1 = Line(Point(1, -2), Point(-1,-2))
+        >>> parabola1 = Parabola(p1, l1)
+        >>> parabola1.intersection(Ellipse(Point(0, 0), 2, 5))
+        [Point2D(-2, 0), Point2D(2, 0)]
+        >>> parabola1.intersection(Line(Point(-7, 3), Point(12, 3)))
+        [Point2D(-4, 3), Point2D(4, 3)]
+        >>> parabola1.intersection(Segment((-12, -65), (14, -68)))
+        []
+
+        """
+        x, y = symbols('x y', real=True)
+        parabola_eq = self.equation()
+        if isinstance(o, Parabola):
+            if o in self:
+                return [o]
+            else:
+                return list(ordered([Point(i) for i in solve(
+                    [parabola_eq, o.equation()], [x, y], set=True)[1]]))
+        elif isinstance(o, Point2D):
+            if simplify(parabola_eq.subs([(x, o._args[0]), (y, o._args[1])])) == 0:
+                return [o]
+            else:
+                return []
+        elif isinstance(o, (Segment2D, Ray2D)):
+            result = solve([parabola_eq,
+                Line2D(o.points[0], o.points[1]).equation()],
+                [x, y], set=True)[1]
+            return list(ordered([Point2D(i) for i in result if i in o]))
+        elif isinstance(o, (Line2D, Ellipse)):
+            return list(ordered([Point2D(i) for i in solve(
+                [parabola_eq, o.equation()], [x, y], set=True)[1]]))
+        elif isinstance(o, LinearEntity3D):
+            raise TypeError('Entity must be two dimensional, not three dimensional')
+        else:
+            raise TypeError('Wrong type of argument were put')
+
+    @property
+    def p_parameter(self):
+        """P is a parameter of parabola.
+
+        Returns
+        =======
+
+        p : number or symbolic expression
+
+        Notes
+        =====
+
+        The absolute value of p is the focal length. The sign on p tells
+        which way the parabola faces. Vertical parabolas that open up
+        and horizontal that open right, give a positive value for p.
+        Vertical parabolas that open down and horizontal that open left,
+        give a negative value for p.
+
+
+        See Also
+        ========
+
+        https://www.sparknotes.com/math/precalc/conicsections/section2/
+
+        Examples
+        ========
+
+        >>> from sympy import Parabola, Point, Line
+        >>> p1 = Parabola(Point(0, 0), Line(Point(5, 8), Point(7, 8)))
+        >>> p1.p_parameter
+        -4
+
+        """
+        m = self.directrix.slope
+        if m is S.Infinity:
+            x = self.directrix.coefficients[2]
+            p = sign(self.focus.args[0] + x)
+        elif m == 0:
+            y = self.directrix.coefficients[2]
+            p = sign(self.focus.args[1] + y)
+        else:
+            d = self.directrix.projection(self.focus)
+            p = sign(self.focus.x - d.x)
+        return p * self.focal_length
+
+    @property
+    def vertex(self):
+        """The vertex of the parabola.
+
+        Returns
+        =======
+
+        vertex : Point
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point
+
+        Examples
+        ========
+
+        >>> from sympy import Parabola, Point, Line
+        >>> p1 = Parabola(Point(0, 0), Line(Point(5, 8), Point(7, 8)))
+        >>> p1.vertex
+        Point2D(0, 4)
+
+        """
+        focus = self.focus
+        m = self.directrix.slope
+        if m is S.Infinity:
+            vertex = Point(focus.args[0] - self.p_parameter, focus.args[1])
+        elif m == 0:
+            vertex = Point(focus.args[0], focus.args[1] - self.p_parameter)
+        else:
+            vertex = self.axis_of_symmetry.intersection(self)[0]
+        return vertex

.venv/lib/python3.13/site-packages/sympy/geometry/plane.py

@@ -0,0 +1,878 @@
+"""Geometrical Planes.
+
+Contains
+========
+Plane
+
+"""
+
+from sympy.core import Dummy, Rational, S, Symbol
+from sympy.core.symbol import _symbol
+from sympy.functions.elementary.trigonometric import cos, sin, acos, asin, sqrt
+from .entity import GeometryEntity
+from .line import (Line, Ray, Segment, Line3D, LinearEntity, LinearEntity3D,
+                   Ray3D, Segment3D)
+from .point import Point, Point3D
+from sympy.matrices import Matrix
+from sympy.polys.polytools import cancel
+from sympy.solvers import solve, linsolve
+from sympy.utilities.iterables import uniq, is_sequence
+from sympy.utilities.misc import filldedent, func_name, Undecidable
+
+from mpmath.libmp.libmpf import prec_to_dps
+
+import random
+
+
+x, y, z, t = [Dummy('plane_dummy') for i in range(4)]
+
+
+class Plane(GeometryEntity):
+    """
+    A plane is a flat, two-dimensional surface. A plane is the two-dimensional
+    analogue of a point (zero-dimensions), a line (one-dimension) and a solid
+    (three-dimensions). A plane can generally be constructed by two types of
+    inputs. They are:
+    - three non-collinear points
+    - a point and the plane's normal vector
+
+    Attributes
+    ==========
+
+    p1
+    normal_vector
+
+    Examples
+    ========
+
+    >>> from sympy import Plane, Point3D
+    >>> Plane(Point3D(1, 1, 1), Point3D(2, 3, 4), Point3D(2, 2, 2))
+    Plane(Point3D(1, 1, 1), (-1, 2, -1))
+    >>> Plane((1, 1, 1), (2, 3, 4), (2, 2, 2))
+    Plane(Point3D(1, 1, 1), (-1, 2, -1))
+    >>> Plane(Point3D(1, 1, 1), normal_vector=(1,4,7))
+    Plane(Point3D(1, 1, 1), (1, 4, 7))
+
+    """
+    def __new__(cls, p1, a=None, b=None, **kwargs):
+        p1 = Point3D(p1, dim=3)
+        if a and b:
+            p2 = Point(a, dim=3)
+            p3 = Point(b, dim=3)
+            if Point3D.are_collinear(p1, p2, p3):
+                raise ValueError('Enter three non-collinear points')
+            a = p1.direction_ratio(p2)
+            b = p1.direction_ratio(p3)
+            normal_vector = tuple(Matrix(a).cross(Matrix(b)))
+        else:
+            a = kwargs.pop('normal_vector', a)
+            evaluate = kwargs.get('evaluate', True)
+            if is_sequence(a) and len(a) == 3:
+                normal_vector = Point3D(a).args if evaluate else a
+            else:
+                raise ValueError(filldedent('''
+                    Either provide 3 3D points or a point with a
+                    normal vector expressed as a sequence of length 3'''))
+            if all(coord.is_zero for coord in normal_vector):
+                raise ValueError('Normal vector cannot be zero vector')
+        return GeometryEntity.__new__(cls, p1, normal_vector, **kwargs)
+
+    def __contains__(self, o):
+        k = self.equation(x, y, z)
+        if isinstance(o, (LinearEntity, LinearEntity3D)):
+            d = Point3D(o.arbitrary_point(t))
+            e = k.subs([(x, d.x), (y, d.y), (z, d.z)])
+            return e.equals(0)
+        try:
+            o = Point(o, dim=3, strict=True)
+            d = k.xreplace(dict(zip((x, y, z), o.args)))
+            return d.equals(0)
+        except TypeError:
+            return False
+
+    def _eval_evalf(self, prec=15, **options):
+        pt, tup = self.args
+        dps = prec_to_dps(prec)
+        pt = pt.evalf(n=dps, **options)
+        tup = tuple([i.evalf(n=dps, **options) for i in tup])
+        return self.func(pt, normal_vector=tup, evaluate=False)
+
+    def angle_between(self, o):
+        """Angle between the plane and other geometric entity.
+
+        Parameters
+        ==========
+
+        LinearEntity3D, Plane.
+
+        Returns
+        =======
+
+        angle : angle in radians
+
+        Notes
+        =====
+
+        This method accepts only 3D entities as it's parameter, but if you want
+        to calculate the angle between a 2D entity and a plane you should
+        first convert to a 3D entity by projecting onto a desired plane and
+        then proceed to calculate the angle.
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D, Line3D, Plane
+        >>> a = Plane(Point3D(1, 2, 2), normal_vector=(1, 2, 3))
+        >>> b = Line3D(Point3D(1, 3, 4), Point3D(2, 2, 2))
+        >>> a.angle_between(b)
+        -asin(sqrt(21)/6)
+
+        """
+        if isinstance(o, LinearEntity3D):
+            a = Matrix(self.normal_vector)
+            b = Matrix(o.direction_ratio)
+            c = a.dot(b)
+            d = sqrt(sum(i**2 for i in self.normal_vector))
+            e = sqrt(sum(i**2 for i in o.direction_ratio))
+            return asin(c/(d*e))
+        if isinstance(o, Plane):
+            a = Matrix(self.normal_vector)
+            b = Matrix(o.normal_vector)
+            c = a.dot(b)
+            d = sqrt(sum(i**2 for i in self.normal_vector))
+            e = sqrt(sum(i**2 for i in o.normal_vector))
+            return acos(c/(d*e))
+
+
+    def arbitrary_point(self, u=None, v=None):
+        """ Returns an arbitrary point on the Plane. If given two
+        parameters, the point ranges over the entire plane. If given 1
+        or no parameters, returns a point with one parameter which,
+        when varying from 0 to 2*pi, moves the point in a circle of
+        radius 1 about p1 of the Plane.
+
+        Examples
+        ========
+
+        >>> from sympy import Plane, Ray
+        >>> from sympy.abc import u, v, t, r
+        >>> p = Plane((1, 1, 1), normal_vector=(1, 0, 0))
+        >>> p.arbitrary_point(u, v)
+        Point3D(1, u + 1, v + 1)
+        >>> p.arbitrary_point(t)
+        Point3D(1, cos(t) + 1, sin(t) + 1)
+
+        While arbitrary values of u and v can move the point anywhere in
+        the plane, the single-parameter point can be used to construct a
+        ray whose arbitrary point can be located at angle t and radius
+        r from p.p1:
+
+        >>> Ray(p.p1, _).arbitrary_point(r)
+        Point3D(1, r*cos(t) + 1, r*sin(t) + 1)
+
+        Returns
+        =======
+
+        Point3D
+
+        """
+        circle = v is None
+        if circle:
+            u = _symbol(u or 't', real=True)
+        else:
+            u = _symbol(u or 'u', real=True)
+            v = _symbol(v or 'v', real=True)
+        x, y, z = self.normal_vector
+        a, b, c = self.p1.args
+        # x1, y1, z1 is a nonzero vector parallel to the plane
+        if x.is_zero and y.is_zero:
+            x1, y1, z1 = S.One, S.Zero, S.Zero
+        else:
+            x1, y1, z1 = -y, x, S.Zero
+        # x2, y2, z2 is also parallel to the plane, and orthogonal to x1, y1, z1
+        x2, y2, z2 = tuple(Matrix((x, y, z)).cross(Matrix((x1, y1, z1))))
+        if circle:
+            x1, y1, z1 = (w/sqrt(x1**2 + y1**2 + z1**2) for w in (x1, y1, z1))
+            x2, y2, z2 = (w/sqrt(x2**2 + y2**2 + z2**2) for w in (x2, y2, z2))
+            p = Point3D(a + x1*cos(u) + x2*sin(u), \
+                        b + y1*cos(u) + y2*sin(u), \
+                        c + z1*cos(u) + z2*sin(u))
+        else:
+            p = Point3D(a + x1*u + x2*v, b + y1*u + y2*v, c + z1*u + z2*v)
+        return p
+
+
+    @staticmethod
+    def are_concurrent(*planes):
+        """Is a sequence of Planes concurrent?
+
+        Two or more Planes are concurrent if their intersections
+        are a common line.
+
+        Parameters
+        ==========
+
+        planes: list
+
+        Returns
+        =======
+
+        Boolean
+
+        Examples
+        ========
+
+        >>> from sympy import Plane, Point3D
+        >>> a = Plane(Point3D(5, 0, 0), normal_vector=(1, -1, 1))
+        >>> b = Plane(Point3D(0, -2, 0), normal_vector=(3, 1, 1))
+        >>> c = Plane(Point3D(0, -1, 0), normal_vector=(5, -1, 9))
+        >>> Plane.are_concurrent(a, b)
+        True
+        >>> Plane.are_concurrent(a, b, c)
+        False
+
+        """
+        planes = list(uniq(planes))
+        for i in planes:
+            if not isinstance(i, Plane):
+                raise ValueError('All objects should be Planes but got %s' % i.func)
+        if len(planes) < 2:
+            return False
+        planes = list(planes)
+        first = planes.pop(0)
+        sol = first.intersection(planes[0])
+        if sol == []:
+            return False
+        else:
+            line = sol[0]
+            for i in planes[1:]:
+                l = first.intersection(i)
+                if not l or l[0] not in line:
+                    return False
+            return True
+
+
+    def distance(self, o):
+        """Distance between the plane and another geometric entity.
+
+        Parameters
+        ==========
+
+        Point3D, LinearEntity3D, Plane.
+
+        Returns
+        =======
+
+        distance
+
+        Notes
+        =====
+
+        This method accepts only 3D entities as it's parameter, but if you want
+        to calculate the distance between a 2D entity and a plane you should
+        first convert to a 3D entity by projecting onto a desired plane and
+        then proceed to calculate the distance.
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D, Line3D, Plane
+        >>> a = Plane(Point3D(1, 1, 1), normal_vector=(1, 1, 1))
+        >>> b = Point3D(1, 2, 3)
+        >>> a.distance(b)
+        sqrt(3)
+        >>> c = Line3D(Point3D(2, 3, 1), Point3D(1, 2, 2))
+        >>> a.distance(c)
+        0
+
+        """
+        if self.intersection(o) != []:
+            return S.Zero
+
+        if isinstance(o, (Segment3D, Ray3D)):
+            a, b = o.p1, o.p2
+            pi, = self.intersection(Line3D(a, b))
+            if pi in o:
+                return self.distance(pi)
+            elif a in Segment3D(pi, b):
+                return self.distance(a)
+            else:
+                assert isinstance(o, Segment3D) is True
+                return self.distance(b)
+
+        # following code handles `Point3D`, `LinearEntity3D`, `Plane`
+        a = o if isinstance(o, Point3D) else o.p1
+        n = Point3D(self.normal_vector).unit
+        d = (a - self.p1).dot(n)
+        return abs(d)
+
+
+    def equals(self, o):
+        """
+        Returns True if self and o are the same mathematical entities.
+
+        Examples
+        ========
+
+        >>> from sympy import Plane, Point3D
+        >>> a = Plane(Point3D(1, 2, 3), normal_vector=(1, 1, 1))
+        >>> b = Plane(Point3D(1, 2, 3), normal_vector=(2, 2, 2))
+        >>> c = Plane(Point3D(1, 2, 3), normal_vector=(-1, 4, 6))
+        >>> a.equals(a)
+        True
+        >>> a.equals(b)
+        True
+        >>> a.equals(c)
+        False
+        """
+        if isinstance(o, Plane):
+            a = self.equation()
+            b = o.equation()
+            return cancel(a/b).is_constant()
+        else:
+            return False
+
+
+    def equation(self, x=None, y=None, z=None):
+        """The equation of the Plane.
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D, Plane
+        >>> a = Plane(Point3D(1, 1, 2), Point3D(2, 4, 7), Point3D(3, 5, 1))
+        >>> a.equation()
+        -23*x + 11*y - 2*z + 16
+        >>> a = Plane(Point3D(1, 4, 2), normal_vector=(6, 6, 6))
+        >>> a.equation()
+        6*x + 6*y + 6*z - 42
+
+        """
+        x, y, z = [i if i else Symbol(j, real=True) for i, j in zip((x, y, z), 'xyz')]
+        a = Point3D(x, y, z)
+        b = self.p1.direction_ratio(a)
+        c = self.normal_vector
+        return (sum(i*j for i, j in zip(b, c)))
+
+
+    def intersection(self, o):
+        """ The intersection with other geometrical entity.
+
+        Parameters
+        ==========
+
+        Point, Point3D, LinearEntity, LinearEntity3D, Plane
+
+        Returns
+        =======
+
+        List
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D, Line3D, Plane
+        >>> a = Plane(Point3D(1, 2, 3), normal_vector=(1, 1, 1))
+        >>> b = Point3D(1, 2, 3)
+        >>> a.intersection(b)
+        [Point3D(1, 2, 3)]
+        >>> c = Line3D(Point3D(1, 4, 7), Point3D(2, 2, 2))
+        >>> a.intersection(c)
+        [Point3D(2, 2, 2)]
+        >>> d = Plane(Point3D(6, 0, 0), normal_vector=(2, -5, 3))
+        >>> e = Plane(Point3D(2, 0, 0), normal_vector=(3, 4, -3))
+        >>> d.intersection(e)
+        [Line3D(Point3D(78/23, -24/23, 0), Point3D(147/23, 321/23, 23))]
+
+        """
+        if not isinstance(o, GeometryEntity):
+            o = Point(o, dim=3)
+        if isinstance(o, Point):
+            if o in self:
+                return [o]
+            else:
+                return []
+        if isinstance(o, (LinearEntity, LinearEntity3D)):
+            # recast to 3D
+            p1, p2 = o.p1, o.p2
+            if isinstance(o, Segment):
+                o = Segment3D(p1, p2)
+            elif isinstance(o, Ray):
+                o = Ray3D(p1, p2)
+            elif isinstance(o, Line):
+                o = Line3D(p1, p2)
+            else:
+                raise ValueError('unhandled linear entity: %s' % o.func)
+            if o in self:
+                return [o]
+            else:
+                a = Point3D(o.arbitrary_point(t))
+                p1, n = self.p1, Point3D(self.normal_vector)
+
+                # TODO: Replace solve with solveset, when this line is tested
+                c = solve((a - p1).dot(n), t)
+                if not c:
+                    return []
+                else:
+                    c = [i for i in c if i.is_real is not False]
+                    if len(c) > 1:
+                        c = [i for i in c if i.is_real]
+                    if len(c) != 1:
+                        raise Undecidable("not sure which point is real")
+                    p = a.subs(t, c[0])
+                    if p not in o:
+                        return []  # e.g. a segment might not intersect a plane
+                    return [p]
+        if isinstance(o, Plane):
+            if self.equals(o):
+                return [self]
+            if self.is_parallel(o):
+                return []
+            else:
+                x, y, z = map(Dummy, 'xyz')
+                a, b = Matrix([self.normal_vector]), Matrix([o.normal_vector])
+                c = list(a.cross(b))
+                d = self.equation(x, y, z)
+                e = o.equation(x, y, z)
+                result = list(linsolve([d, e], x, y, z))[0]
+                for i in (x, y, z): result = result.subs(i, 0)
+                return [Line3D(Point3D(result), direction_ratio=c)]
+
+
+    def is_coplanar(self, o):
+        """ Returns True if `o` is coplanar with self, else False.
+
+        Examples
+        ========
+
+        >>> from sympy import Plane
+        >>> o = (0, 0, 0)
+        >>> p = Plane(o, (1, 1, 1))
+        >>> p2 = Plane(o, (2, 2, 2))
+        >>> p == p2
+        False
+        >>> p.is_coplanar(p2)
+        True
+        """
+        if isinstance(o, Plane):
+            return not cancel(self.equation(x, y, z)/o.equation(x, y, z)).has(x, y, z)
+        if isinstance(o, Point3D):
+            return o in self
+        elif isinstance(o, LinearEntity3D):
+            return all(i in self for i in self)
+        elif isinstance(o, GeometryEntity):  # XXX should only be handling 2D objects now
+            return all(i == 0 for i in self.normal_vector[:2])
+
+
+    def is_parallel(self, l):
+        """Is the given geometric entity parallel to the plane?
+
+        Parameters
+        ==========
+
+        LinearEntity3D or Plane
+
+        Returns
+        =======
+
+        Boolean
+
+        Examples
+        ========
+
+        >>> from sympy import Plane, Point3D
+        >>> a = Plane(Point3D(1,4,6), normal_vector=(2, 4, 6))
+        >>> b = Plane(Point3D(3,1,3), normal_vector=(4, 8, 12))
+        >>> a.is_parallel(b)
+        True
+
+        """
+        if isinstance(l, LinearEntity3D):
+            a = l.direction_ratio
+            b = self.normal_vector
+            return sum(i*j for i, j in zip(a, b)) == 0
+        if isinstance(l, Plane):
+            a = Matrix(l.normal_vector)
+            b = Matrix(self.normal_vector)
+            return bool(a.cross(b).is_zero_matrix)
+
+
+    def is_perpendicular(self, l):
+        """Is the given geometric entity perpendicualar to the given plane?
+
+        Parameters
+        ==========
+
+        LinearEntity3D or Plane
+
+        Returns
+        =======
+
+        Boolean
+
+        Examples
+        ========
+
+        >>> from sympy import Plane, Point3D
+        >>> a = Plane(Point3D(1,4,6), normal_vector=(2, 4, 6))
+        >>> b = Plane(Point3D(2, 2, 2), normal_vector=(-1, 2, -1))
+        >>> a.is_perpendicular(b)
+        True
+
+        """
+        if isinstance(l, LinearEntity3D):
+            a = Matrix(l.direction_ratio)
+            b = Matrix(self.normal_vector)
+            if a.cross(b).is_zero_matrix:
+                return True
+            else:
+                return False
+        elif isinstance(l, Plane):
+            a = Matrix(l.normal_vector)
+            b = Matrix(self.normal_vector)
+            if a.dot(b) == 0:
+                return True
+            else:
+                return False
+        else:
+            return False
+
+    @property
+    def normal_vector(self):
+        """Normal vector of the given plane.
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D, Plane
+        >>> a = Plane(Point3D(1, 1, 1), Point3D(2, 3, 4), Point3D(2, 2, 2))
+        >>> a.normal_vector
+        (-1, 2, -1)
+        >>> a = Plane(Point3D(1, 1, 1), normal_vector=(1, 4, 7))
+        >>> a.normal_vector
+        (1, 4, 7)
+
+        """
+        return self.args[1]
+
+    @property
+    def p1(self):
+        """The only defining point of the plane. Others can be obtained from the
+        arbitrary_point method.
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point3D
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D, Plane
+        >>> a = Plane(Point3D(1, 1, 1), Point3D(2, 3, 4), Point3D(2, 2, 2))
+        >>> a.p1
+        Point3D(1, 1, 1)
+
+        """
+        return self.args[0]
+
+    def parallel_plane(self, pt):
+        """
+        Plane parallel to the given plane and passing through the point pt.
+
+        Parameters
+        ==========
+
+        pt: Point3D
+
+        Returns
+        =======
+
+        Plane
+
+        Examples
+        ========
+
+        >>> from sympy import Plane, Point3D
+        >>> a = Plane(Point3D(1, 4, 6), normal_vector=(2, 4, 6))
+        >>> a.parallel_plane(Point3D(2, 3, 5))
+        Plane(Point3D(2, 3, 5), (2, 4, 6))
+
+        """
+        a = self.normal_vector
+        return Plane(pt, normal_vector=a)
+
+    def perpendicular_line(self, pt):
+        """A line perpendicular to the given plane.
+
+        Parameters
+        ==========
+
+        pt: Point3D
+
+        Returns
+        =======
+
+        Line3D
+
+        Examples
+        ========
+
+        >>> from sympy import Plane, Point3D
+        >>> a = Plane(Point3D(1,4,6), normal_vector=(2, 4, 6))
+        >>> a.perpendicular_line(Point3D(9, 8, 7))
+        Line3D(Point3D(9, 8, 7), Point3D(11, 12, 13))
+
+        """
+        a = self.normal_vector
+        return Line3D(pt, direction_ratio=a)
+
+    def perpendicular_plane(self, *pts):
+        """
+        Return a perpendicular passing through the given points. If the
+        direction ratio between the points is the same as the Plane's normal
+        vector then, to select from the infinite number of possible planes,
+        a third point will be chosen on the z-axis (or the y-axis
+        if the normal vector is already parallel to the z-axis). If less than
+        two points are given they will be supplied as follows: if no point is
+        given then pt1 will be self.p1; if a second point is not given it will
+        be a point through pt1 on a line parallel to the z-axis (if the normal
+        is not already the z-axis, otherwise on the line parallel to the
+        y-axis).
+
+        Parameters
+        ==========
+
+        pts: 0, 1 or 2 Point3D
+
+        Returns
+        =======
+
+        Plane
+
+        Examples
+        ========
+
+        >>> from sympy import Plane, Point3D
+        >>> a, b = Point3D(0, 0, 0), Point3D(0, 1, 0)
+        >>> Z = (0, 0, 1)
+        >>> p = Plane(a, normal_vector=Z)
+        >>> p.perpendicular_plane(a, b)
+        Plane(Point3D(0, 0, 0), (1, 0, 0))
+        """
+        if len(pts) > 2:
+            raise ValueError('No more than 2 pts should be provided.')
+
+        pts = list(pts)
+        if len(pts) == 0:
+            pts.append(self.p1)
+        if len(pts) == 1:
+            x, y, z = self.normal_vector
+            if x == y == 0:
+                dir = (0, 1, 0)
+            else:
+                dir = (0, 0, 1)
+            pts.append(pts[0] + Point3D(*dir))
+
+        p1, p2 = [Point(i, dim=3) for i in pts]
+        l = Line3D(p1, p2)
+        n = Line3D(p1, direction_ratio=self.normal_vector)
+        if l in n:  # XXX should an error be raised instead?
+            # there are infinitely many perpendicular planes;
+            x, y, z = self.normal_vector
+            if x == y == 0:
+                # the z axis is the normal so pick a pt on the y-axis
+                p3 = Point3D(0, 1, 0)  # case 1
+            else:
+                # else pick a pt on the z axis
+                p3 = Point3D(0, 0, 1)  # case 2
+            # in case that point is already given, move it a bit
+            if p3 in l:
+                p3 *= 2  # case 3
+        else:
+            p3 = p1 + Point3D(*self.normal_vector)  # case 4
+        return Plane(p1, p2, p3)
+
+    def projection_line(self, line):
+        """Project the given line onto the plane through the normal plane
+        containing the line.
+
+        Parameters
+        ==========
+
+        LinearEntity or LinearEntity3D
+
+        Returns
+        =======
+
+        Point3D, Line3D, Ray3D or Segment3D
+
+        Notes
+        =====
+
+        For the interaction between 2D and 3D lines(segments, rays), you should
+        convert the line to 3D by using this method. For example for finding the
+        intersection between a 2D and a 3D line, convert the 2D line to a 3D line
+        by projecting it on a required plane and then proceed to find the
+        intersection between those lines.
+
+        Examples
+        ========
+
+        >>> from sympy import Plane, Line, Line3D, Point3D
+        >>> a = Plane(Point3D(1, 1, 1), normal_vector=(1, 1, 1))
+        >>> b = Line(Point3D(1, 1), Point3D(2, 2))
+        >>> a.projection_line(b)
+        Line3D(Point3D(4/3, 4/3, 1/3), Point3D(5/3, 5/3, -1/3))
+        >>> c = Line3D(Point3D(1, 1, 1), Point3D(2, 2, 2))
+        >>> a.projection_line(c)
+        Point3D(1, 1, 1)
+
+        """
+        if not isinstance(line, (LinearEntity, LinearEntity3D)):
+            raise NotImplementedError('Enter a linear entity only')
+        a, b = self.projection(line.p1), self.projection(line.p2)
+        if a == b:
+            # projection does not imply intersection so for
+            # this case (line parallel to plane's normal) we
+            # return the projection point
+            return a
+        if isinstance(line, (Line, Line3D)):
+            return Line3D(a, b)
+        if isinstance(line, (Ray, Ray3D)):
+            return Ray3D(a, b)
+        if isinstance(line, (Segment, Segment3D)):
+            return Segment3D(a, b)
+
+    def projection(self, pt):
+        """Project the given point onto the plane along the plane normal.
+
+        Parameters
+        ==========
+
+        Point or Point3D
+
+        Returns
+        =======
+
+        Point3D
+
+        Examples
+        ========
+
+        >>> from sympy import Plane, Point3D
+        >>> A = Plane(Point3D(1, 1, 2), normal_vector=(1, 1, 1))
+
+        The projection is along the normal vector direction, not the z
+        axis, so (1, 1) does not project to (1, 1, 2) on the plane A:
+
+        >>> b = Point3D(1, 1)
+        >>> A.projection(b)
+        Point3D(5/3, 5/3, 2/3)
+        >>> _ in A
+        True
+
+        But the point (1, 1, 2) projects to (1, 1) on the XY-plane:
+
+        >>> XY = Plane((0, 0, 0), (0, 0, 1))
+        >>> XY.projection((1, 1, 2))
+        Point3D(1, 1, 0)
+        """
+        rv = Point(pt, dim=3)
+        if rv in self:
+            return rv
+        return self.intersection(Line3D(rv, rv + Point3D(self.normal_vector)))[0]
+
+    def random_point(self, seed=None):
+        """ Returns a random point on the Plane.
+
+        Returns
+        =======
+
+        Point3D
+
+        Examples
+        ========
+
+        >>> from sympy import Plane
+        >>> p = Plane((1, 0, 0), normal_vector=(0, 1, 0))
+        >>> r = p.random_point(seed=42)  # seed value is optional
+        >>> r.n(3)
+        Point3D(2.29, 0, -1.35)
+
+        The random point can be moved to lie on the circle of radius
+        1 centered on p1:
+
+        >>> c = p.p1 + (r - p.p1).unit
+        >>> c.distance(p.p1).equals(1)
+        True
+        """
+        if seed is not None:
+            rng = random.Random(seed)
+        else:
+            rng = random
+        params = {
+            x: 2*Rational(rng.gauss(0, 1)) - 1,
+            y: 2*Rational(rng.gauss(0, 1)) - 1}
+        return self.arbitrary_point(x, y).subs(params)
+
+    def parameter_value(self, other, u, v=None):
+        """Return the parameter(s) corresponding to the given point.
+
+        Examples
+        ========
+
+        >>> from sympy import pi, Plane
+        >>> from sympy.abc import t, u, v
+        >>> p = Plane((2, 0, 0), (0, 0, 1), (0, 1, 0))
+
+        By default, the parameter value returned defines a point
+        that is a distance of 1 from the Plane's p1 value and
+        in line with the given point:
+
+        >>> on_circle = p.arbitrary_point(t).subs(t, pi/4)
+        >>> on_circle.distance(p.p1)
+        1
+        >>> p.parameter_value(on_circle, t)
+        {t: pi/4}
+
+        Moving the point twice as far from p1 does not change
+        the parameter value:
+
+        >>> off_circle = p.p1 + (on_circle - p.p1)*2
+        >>> off_circle.distance(p.p1)
+        2
+        >>> p.parameter_value(off_circle, t)
+        {t: pi/4}
+
+        If the 2-value parameter is desired, supply the two
+        parameter symbols and a replacement dictionary will
+        be returned:
+
+        >>> p.parameter_value(on_circle, u, v)
+        {u: sqrt(10)/10, v: sqrt(10)/30}
+        >>> p.parameter_value(off_circle, u, v)
+        {u: sqrt(10)/5, v: sqrt(10)/15}
+        """
+        if not isinstance(other, GeometryEntity):
+            other = Point(other, dim=self.ambient_dimension)
+        if not isinstance(other, Point):
+            raise ValueError("other must be a point")
+        if other == self.p1:
+            return other
+        if isinstance(u, Symbol) and v is None:
+            delta = self.arbitrary_point(u) - self.p1
+            eq = delta - (other - self.p1).unit
+            sol = solve(eq, u, dict=True)
+        elif isinstance(u, Symbol) and isinstance(v, Symbol):
+            pt = self.arbitrary_point(u, v)
+            sol = solve(pt - other, (u, v), dict=True)
+        else:
+            raise ValueError('expecting 1 or 2 symbols')
+        if not sol:
+            raise ValueError("Given point is not on %s" % func_name(self))
+        return sol[0]  # {t: tval} or {u: uval, v: vval}
+
+    @property
+    def ambient_dimension(self):
+        return self.p1.ambient_dimension

.venv/lib/python3.13/site-packages/sympy/geometry/point.py

@@ -0,0 +1,1378 @@
+"""Geometrical Points.
+
+Contains
+========
+Point
+Point2D
+Point3D
+
+When methods of Point require 1 or more points as arguments, they
+can be passed as a sequence of coordinates or Points:
+
+>>> from sympy import Point
+>>> Point(1, 1).is_collinear((2, 2), (3, 4))
+False
+>>> Point(1, 1).is_collinear(Point(2, 2), Point(3, 4))
+False
+
+"""
+
+import warnings
+
+from sympy.core import S, sympify, Expr
+from sympy.core.add import Add
+from sympy.core.containers import Tuple
+from sympy.core.numbers import Float
+from sympy.core.parameters import global_parameters
+from sympy.simplify.simplify import nsimplify, simplify
+from sympy.geometry.exceptions import GeometryError
+from sympy.functions.elementary.miscellaneous import sqrt
+from sympy.functions.elementary.complexes import im
+from sympy.functions.elementary.trigonometric import cos, sin
+from sympy.matrices import Matrix
+from sympy.matrices.expressions import Transpose
+from sympy.utilities.iterables import uniq, is_sequence
+from sympy.utilities.misc import filldedent, func_name, Undecidable
+
+from .entity import GeometryEntity
+
+from mpmath.libmp.libmpf import prec_to_dps
+
+
+class Point(GeometryEntity):
+    """A point in a n-dimensional Euclidean space.
+
+    Parameters
+    ==========
+
+    coords : sequence of n-coordinate values. In the special
+        case where n=2 or 3, a Point2D or Point3D will be created
+        as appropriate.
+    evaluate : if `True` (default), all floats are turn into
+        exact types.
+    dim : number of coordinates the point should have.  If coordinates
+        are unspecified, they are padded with zeros.
+    on_morph : indicates what should happen when the number of
+        coordinates of a point need to be changed by adding or
+        removing zeros.  Possible values are `'warn'`, `'error'`, or
+        `ignore` (default).  No warning or error is given when `*args`
+        is empty and `dim` is given. An error is always raised when
+        trying to remove nonzero coordinates.
+
+
+    Attributes
+    ==========
+
+    length
+    origin: A `Point` representing the origin of the
+        appropriately-dimensioned space.
+
+    Raises
+    ======
+
+    TypeError : When instantiating with anything but a Point or sequence
+    ValueError : when instantiating with a sequence with length < 2 or
+        when trying to reduce dimensions if keyword `on_morph='error'` is
+        set.
+
+    See Also
+    ========
+
+    sympy.geometry.line.Segment : Connects two Points
+
+    Examples
+    ========
+
+    >>> from sympy import Point
+    >>> from sympy.abc import x
+    >>> Point(1, 2, 3)
+    Point3D(1, 2, 3)
+    >>> Point([1, 2])
+    Point2D(1, 2)
+    >>> Point(0, x)
+    Point2D(0, x)
+    >>> Point(dim=4)
+    Point(0, 0, 0, 0)
+
+    Floats are automatically converted to Rational unless the
+    evaluate flag is False:
+
+    >>> Point(0.5, 0.25)
+    Point2D(1/2, 1/4)
+    >>> Point(0.5, 0.25, evaluate=False)
+    Point2D(0.5, 0.25)
+
+    """
+
+    is_Point = True
+
+    def __new__(cls, *args, **kwargs):
+        evaluate = kwargs.get('evaluate', global_parameters.evaluate)
+        on_morph = kwargs.get('on_morph', 'ignore')
+
+        # unpack into coords
+        coords = args[0] if len(args) == 1 else args
+
+        # check args and handle quickly handle Point instances
+        if isinstance(coords, Point):
+            # even if we're mutating the dimension of a point, we
+            # don't reevaluate its coordinates
+            evaluate = False
+            if len(coords) == kwargs.get('dim', len(coords)):
+                return coords
+
+        if not is_sequence(coords):
+            raise TypeError(filldedent('''
+                Expecting sequence of coordinates, not `{}`'''
+                                       .format(func_name(coords))))
+        # A point where only `dim` is specified is initialized
+        # to zeros.
+        if len(coords) == 0 and kwargs.get('dim', None):
+            coords = (S.Zero,)*kwargs.get('dim')
+
+        coords = Tuple(*coords)
+        dim = kwargs.get('dim', len(coords))
+
+        if len(coords) < 2:
+            raise ValueError(filldedent('''
+                Point requires 2 or more coordinates or
+                keyword `dim` > 1.'''))
+        if len(coords) != dim:
+            message = ("Dimension of {} needs to be changed "
+                       "from {} to {}.").format(coords, len(coords), dim)
+            if on_morph == 'ignore':
+                pass
+            elif on_morph == "error":
+                raise ValueError(message)
+            elif on_morph == 'warn':
+                warnings.warn(message, stacklevel=2)
+            else:
+                raise ValueError(filldedent('''
+                        on_morph value should be 'error',
+                        'warn' or 'ignore'.'''))
+        if any(coords[dim:]):
+            raise ValueError('Nonzero coordinates cannot be removed.')
+        if any(a.is_number and im(a).is_zero is False for a in coords):
+            raise ValueError('Imaginary coordinates are not permitted.')
+        if not all(isinstance(a, Expr) for a in coords):
+            raise TypeError('Coordinates must be valid SymPy expressions.')
+
+        # pad with zeros appropriately
+        coords = coords[:dim] + (S.Zero,)*(dim - len(coords))
+
+        # Turn any Floats into rationals and simplify
+        # any expressions before we instantiate
+        if evaluate:
+            coords = coords.xreplace({
+                f: simplify(nsimplify(f, rational=True))
+                 for f in coords.atoms(Float)})
+
+        # return 2D or 3D instances
+        if len(coords) == 2:
+            kwargs['_nocheck'] = True
+            return Point2D(*coords, **kwargs)
+        elif len(coords) == 3:
+            kwargs['_nocheck'] = True
+            return Point3D(*coords, **kwargs)
+
+        # the general Point
+        return GeometryEntity.__new__(cls, *coords)
+
+    def __abs__(self):
+        """Returns the distance between this point and the origin."""
+        origin = Point([0]*len(self))
+        return Point.distance(origin, self)
+
+    def __add__(self, other):
+        """Add other to self by incrementing self's coordinates by
+        those of other.
+
+        Notes
+        =====
+
+        >>> from sympy import Point
+
+        When sequences of coordinates are passed to Point methods, they
+        are converted to a Point internally. This __add__ method does
+        not do that so if floating point values are used, a floating
+        point result (in terms of SymPy Floats) will be returned.
+
+        >>> Point(1, 2) + (.1, .2)
+        Point2D(1.1, 2.2)
+
+        If this is not desired, the `translate` method can be used or
+        another Point can be added:
+
+        >>> Point(1, 2).translate(.1, .2)
+        Point2D(11/10, 11/5)
+        >>> Point(1, 2) + Point(.1, .2)
+        Point2D(11/10, 11/5)
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point.translate
+
+        """
+        try:
+            s, o = Point._normalize_dimension(self, Point(other, evaluate=False))
+        except TypeError:
+            raise GeometryError("Don't know how to add {} and a Point object".format(other))
+
+        coords = [simplify(a + b) for a, b in zip(s, o)]
+        return Point(coords, evaluate=False)
+
+    def __contains__(self, item):
+        return item in self.args
+
+    def __truediv__(self, divisor):
+        """Divide point's coordinates by a factor."""
+        divisor = sympify(divisor)
+        coords = [simplify(x/divisor) for x in self.args]
+        return Point(coords, evaluate=False)
+
+    def __eq__(self, other):
+        if not isinstance(other, Point) or len(self.args) != len(other.args):
+            return False
+        return self.args == other.args
+
+    def __getitem__(self, key):
+        return self.args[key]
+
+    def __hash__(self):
+        return hash(self.args)
+
+    def __iter__(self):
+        return self.args.__iter__()
+
+    def __len__(self):
+        return len(self.args)
+
+    def __mul__(self, factor):
+        """Multiply point's coordinates by a factor.
+
+        Notes
+        =====
+
+        >>> from sympy import Point
+
+        When multiplying a Point by a floating point number,
+        the coordinates of the Point will be changed to Floats:
+
+        >>> Point(1, 2)*0.1
+        Point2D(0.1, 0.2)
+
+        If this is not desired, the `scale` method can be used or
+        else only multiply or divide by integers:
+
+        >>> Point(1, 2).scale(1.1, 1.1)
+        Point2D(11/10, 11/5)
+        >>> Point(1, 2)*11/10
+        Point2D(11/10, 11/5)
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point.scale
+        """
+        factor = sympify(factor)
+        coords = [simplify(x*factor) for x in self.args]
+        return Point(coords, evaluate=False)
+
+    def __rmul__(self, factor):
+        """Multiply a factor by point's coordinates."""
+        return self.__mul__(factor)
+
+    def __neg__(self):
+        """Negate the point."""
+        coords = [-x for x in self.args]
+        return Point(coords, evaluate=False)
+
+    def __sub__(self, other):
+        """Subtract two points, or subtract a factor from this point's
+        coordinates."""
+        return self + [-x for x in other]
+
+    @classmethod
+    def _normalize_dimension(cls, *points, **kwargs):
+        """Ensure that points have the same dimension.
+        By default `on_morph='warn'` is passed to the
+        `Point` constructor."""
+        # if we have a built-in ambient dimension, use it
+        dim = getattr(cls, '_ambient_dimension', None)
+        # override if we specified it
+        dim = kwargs.get('dim', dim)
+        # if no dim was given, use the highest dimensional point
+        if dim is None:
+            dim = max(i.ambient_dimension for i in points)
+        if all(i.ambient_dimension == dim for i in points):
+            return list(points)
+        kwargs['dim'] = dim
+        kwargs['on_morph'] = kwargs.get('on_morph', 'warn')
+        return [Point(i, **kwargs) for i in points]
+
+    @staticmethod
+    def affine_rank(*args):
+        """The affine rank of a set of points is the dimension
+        of the smallest affine space containing all the points.
+        For example, if the points lie on a line (and are not all
+        the same) their affine rank is 1.  If the points lie on a plane
+        but not a line, their affine rank is 2.  By convention, the empty
+        set has affine rank -1."""
+
+        if len(args) == 0:
+            return -1
+        # make sure we're genuinely points
+        # and translate every point to the origin
+        points = Point._normalize_dimension(*[Point(i) for i in args])
+        origin = points[0]
+        points = [i - origin for i in points[1:]]
+
+        m = Matrix([i.args for i in points])
+        # XXX fragile -- what is a better way?
+        return m.rank(iszerofunc = lambda x:
+            abs(x.n(2)) < 1e-12 if x.is_number else x.is_zero)
+
+    @property
+    def ambient_dimension(self):
+        """Number of components this point has."""
+        return getattr(self, '_ambient_dimension', len(self))
+
+    @classmethod
+    def are_coplanar(cls, *points):
+        """Return True if there exists a plane in which all the points
+        lie.  A trivial True value is returned if `len(points) < 3` or
+        all Points are 2-dimensional.
+
+        Parameters
+        ==========
+
+        A set of points
+
+        Raises
+        ======
+
+        ValueError : if less than 3 unique points are given
+
+        Returns
+        =======
+
+        boolean
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D
+        >>> p1 = Point3D(1, 2, 2)
+        >>> p2 = Point3D(2, 7, 2)
+        >>> p3 = Point3D(0, 0, 2)
+        >>> p4 = Point3D(1, 1, 2)
+        >>> Point3D.are_coplanar(p1, p2, p3, p4)
+        True
+        >>> p5 = Point3D(0, 1, 3)
+        >>> Point3D.are_coplanar(p1, p2, p3, p5)
+        False
+
+        """
+        if len(points) <= 1:
+            return True
+
+        points = cls._normalize_dimension(*[Point(i) for i in points])
+        # quick exit if we are in 2D
+        if points[0].ambient_dimension == 2:
+            return True
+        points = list(uniq(points))
+        return Point.affine_rank(*points) <= 2
+
+    def distance(self, other):
+        """The Euclidean distance between self and another GeometricEntity.
+
+        Returns
+        =======
+
+        distance : number or symbolic expression.
+
+        Raises
+        ======
+
+        TypeError : if other is not recognized as a GeometricEntity or is a
+                    GeometricEntity for which distance is not defined.
+
+        See Also
+        ========
+
+        sympy.geometry.line.Segment.length
+        sympy.geometry.point.Point.taxicab_distance
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Line
+        >>> p1, p2 = Point(1, 1), Point(4, 5)
+        >>> l = Line((3, 1), (2, 2))
+        >>> p1.distance(p2)
+        5
+        >>> p1.distance(l)
+        sqrt(2)
+
+        The computed distance may be symbolic, too:
+
+        >>> from sympy.abc import x, y
+        >>> p3 = Point(x, y)
+        >>> p3.distance((0, 0))
+        sqrt(x**2 + y**2)
+
+        """
+        if not isinstance(other, GeometryEntity):
+            try:
+                other = Point(other, dim=self.ambient_dimension)
+            except TypeError:
+                raise TypeError("not recognized as a GeometricEntity: %s" % type(other))
+        if isinstance(other, Point):
+            s, p = Point._normalize_dimension(self, Point(other))
+            return sqrt(Add(*((a - b)**2 for a, b in zip(s, p))))
+        distance = getattr(other, 'distance', None)
+        if distance is None:
+            raise TypeError("distance between Point and %s is not defined" % type(other))
+        return distance(self)
+
+    def dot(self, p):
+        """Return dot product of self with another Point."""
+        if not is_sequence(p):
+            p = Point(p)  # raise the error via Point
+        return Add(*(a*b for a, b in zip(self, p)))
+
+    def equals(self, other):
+        """Returns whether the coordinates of self and other agree."""
+        # a point is equal to another point if all its components are equal
+        if not isinstance(other, Point) or len(self) != len(other):
+            return False
+        return all(a.equals(b) for a, b in zip(self, other))
+
+    def _eval_evalf(self, prec=15, **options):
+        """Evaluate the coordinates of the point.
+
+        This method will, where possible, create and return a new Point
+        where the coordinates are evaluated as floating point numbers to
+        the precision indicated (default=15).
+
+        Parameters
+        ==========
+
+        prec : int
+
+        Returns
+        =======
+
+        point : Point
+
+        Examples
+        ========
+
+        >>> from sympy import Point, Rational
+        >>> p1 = Point(Rational(1, 2), Rational(3, 2))
+        >>> p1
+        Point2D(1/2, 3/2)
+        >>> p1.evalf()
+        Point2D(0.5, 1.5)
+
+        """
+        dps = prec_to_dps(prec)
+        coords = [x.evalf(n=dps, **options) for x in self.args]
+        return Point(*coords, evaluate=False)
+
+    def intersection(self, other):
+        """The intersection between this point and another GeometryEntity.
+
+        Parameters
+        ==========
+
+        other : GeometryEntity or sequence of coordinates
+
+        Returns
+        =======
+
+        intersection : list of Points
+
+        Notes
+        =====
+
+        The return value will either be an empty list if there is no
+        intersection, otherwise it will contain this point.
+
+        Examples
+        ========
+
+        >>> from sympy import Point
+        >>> p1, p2, p3 = Point(0, 0), Point(1, 1), Point(0, 0)
+        >>> p1.intersection(p2)
+        []
+        >>> p1.intersection(p3)
+        [Point2D(0, 0)]
+
+        """
+        if not isinstance(other, GeometryEntity):
+            other = Point(other)
+        if isinstance(other, Point):
+            if self == other:
+                return [self]
+            p1, p2 = Point._normalize_dimension(self, other)
+            if p1 == self and p1 == p2:
+                return [self]
+            return []
+        return other.intersection(self)
+
+    def is_collinear(self, *args):
+        """Returns `True` if there exists a line
+        that contains `self` and `points`.  Returns `False` otherwise.
+        A trivially True value is returned if no points are given.
+
+        Parameters
+        ==========
+
+        args : sequence of Points
+
+        Returns
+        =======
+
+        is_collinear : boolean
+
+        See Also
+        ========
+
+        sympy.geometry.line.Line
+
+        Examples
+        ========
+
+        >>> from sympy import Point
+        >>> from sympy.abc import x
+        >>> p1, p2 = Point(0, 0), Point(1, 1)
+        >>> p3, p4, p5 = Point(2, 2), Point(x, x), Point(1, 2)
+        >>> Point.is_collinear(p1, p2, p3, p4)
+        True
+        >>> Point.is_collinear(p1, p2, p3, p5)
+        False
+
+        """
+        points = (self,) + args
+        points = Point._normalize_dimension(*[Point(i) for i in points])
+        points = list(uniq(points))
+        return Point.affine_rank(*points) <= 1
+
+    def is_concyclic(self, *args):
+        """Do `self` and the given sequence of points lie in a circle?
+
+        Returns True if the set of points are concyclic and
+        False otherwise. A trivial value of True is returned
+        if there are fewer than 2 other points.
+
+        Parameters
+        ==========
+
+        args : sequence of Points
+
+        Returns
+        =======
+
+        is_concyclic : boolean
+
+
+        Examples
+        ========
+
+        >>> from sympy import Point
+
+        Define 4 points that are on the unit circle:
+
+        >>> p1, p2, p3, p4 = Point(1, 0), (0, 1), (-1, 0), (0, -1)
+
+        >>> p1.is_concyclic() == p1.is_concyclic(p2, p3, p4) == True
+        True
+
+        Define a point not on that circle:
+
+        >>> p = Point(1, 1)
+
+        >>> p.is_concyclic(p1, p2, p3)
+        False
+
+        """
+        points = (self,) + args
+        points = Point._normalize_dimension(*[Point(i) for i in points])
+        points = list(uniq(points))
+        if not Point.affine_rank(*points) <= 2:
+            return False
+        origin = points[0]
+        points = [p - origin for p in points]
+        # points are concyclic if they are coplanar and
+        # there is a point c so that ||p_i-c|| == ||p_j-c|| for all
+        # i and j.  Rearranging this equation gives us the following
+        # condition: the matrix `mat` must not a pivot in the last
+        # column.
+        mat = Matrix([list(i) + [i.dot(i)] for i in points])
+        rref, pivots = mat.rref()
+        if len(origin) not in pivots:
+            return True
+        return False
+
+    @property
+    def is_nonzero(self):
+        """True if any coordinate is nonzero, False if every coordinate is zero,
+        and None if it cannot be determined."""
+        is_zero = self.is_zero
+        if is_zero is None:
+            return None
+        return not is_zero
+
+    def is_scalar_multiple(self, p):
+        """Returns whether each coordinate of `self` is a scalar
+        multiple of the corresponding coordinate in point p.
+        """
+        s, o = Point._normalize_dimension(self, Point(p))
+        # 2d points happen a lot, so optimize this function call
+        if s.ambient_dimension == 2:
+            (x1, y1), (x2, y2) = s.args, o.args
+            rv = (x1*y2 - x2*y1).equals(0)
+            if rv is None:
+                raise Undecidable(filldedent(
+                    '''Cannot determine if %s is a scalar multiple of
+                    %s''' % (s, o)))
+
+        # if the vectors p1 and p2 are linearly dependent, then they must
+        # be scalar multiples of each other
+        m = Matrix([s.args, o.args])
+        return m.rank() < 2
+
+    @property
+    def is_zero(self):
+        """True if every coordinate is zero, False if any coordinate is not zero,
+        and None if it cannot be determined."""
+        nonzero = [x.is_nonzero for x in self.args]
+        if any(nonzero):
+            return False
+        if any(x is None for x in nonzero):
+            return None
+        return True
+
+    @property
+    def length(self):
+        """
+        Treating a Point as a Line, this returns 0 for the length of a Point.
+
+        Examples
+        ========
+
+        >>> from sympy import Point
+        >>> p = Point(0, 1)
+        >>> p.length
+        0
+        """
+        return S.Zero
+
+    def midpoint(self, p):
+        """The midpoint between self and point p.
+
+        Parameters
+        ==========
+
+        p : Point
+
+        Returns
+        =======
+
+        midpoint : Point
+
+        See Also
+        ========
+
+        sympy.geometry.line.Segment.midpoint
+
+        Examples
+        ========
+
+        >>> from sympy import Point
+        >>> p1, p2 = Point(1, 1), Point(13, 5)
+        >>> p1.midpoint(p2)
+        Point2D(7, 3)
+
+        """
+        s, p = Point._normalize_dimension(self, Point(p))
+        return Point([simplify((a + b)*S.Half) for a, b in zip(s, p)])
+
+    @property
+    def origin(self):
+        """A point of all zeros of the same ambient dimension
+        as the current point"""
+        return Point([0]*len(self), evaluate=False)
+
+    @property
+    def orthogonal_direction(self):
+        """Returns a non-zero point that is orthogonal to the
+        line containing `self` and the origin.
+
+        Examples
+        ========
+
+        >>> from sympy import Line, Point
+        >>> a = Point(1, 2, 3)
+        >>> a.orthogonal_direction
+        Point3D(-2, 1, 0)
+        >>> b = _
+        >>> Line(b, b.origin).is_perpendicular(Line(a, a.origin))
+        True
+        """
+        dim = self.ambient_dimension
+        # if a coordinate is zero, we can put a 1 there and zeros elsewhere
+        if self[0].is_zero:
+            return Point([1] + (dim - 1)*[0])
+        if self[1].is_zero:
+            return Point([0,1] + (dim - 2)*[0])
+        # if the first two coordinates aren't zero, we can create a non-zero
+        # orthogonal vector by swapping them, negating one, and padding with zeros
+        return Point([-self[1], self[0]] + (dim - 2)*[0])
+
+    @staticmethod
+    def project(a, b):
+        """Project the point `a` onto the line between the origin
+        and point `b` along the normal direction.
+
+        Parameters
+        ==========
+
+        a : Point
+        b : Point
+
+        Returns
+        =======
+
+        p : Point
+
+        See Also
+        ========
+
+        sympy.geometry.line.LinearEntity.projection
+
+        Examples
+        ========
+
+        >>> from sympy import Line, Point
+        >>> a = Point(1, 2)
+        >>> b = Point(2, 5)
+        >>> z = a.origin
+        >>> p = Point.project(a, b)
+        >>> Line(p, a).is_perpendicular(Line(p, b))
+        True
+        >>> Point.is_collinear(z, p, b)
+        True
+        """
+        a, b = Point._normalize_dimension(Point(a), Point(b))
+        if b.is_zero:
+            raise ValueError("Cannot project to the zero vector.")
+        return b*(a.dot(b) / b.dot(b))
+
+    def taxicab_distance(self, p):
+        """The Taxicab Distance from self to point p.
+
+        Returns the sum of the horizontal and vertical distances to point p.
+
+        Parameters
+        ==========
+
+        p : Point
+
+        Returns
+        =======
+
+        taxicab_distance : The sum of the horizontal
+        and vertical distances to point p.
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point.distance
+
+        Examples
+        ========
+
+        >>> from sympy import Point
+        >>> p1, p2 = Point(1, 1), Point(4, 5)
+        >>> p1.taxicab_distance(p2)
+        7
+
+        """
+        s, p = Point._normalize_dimension(self, Point(p))
+        return Add(*(abs(a - b) for a, b in zip(s, p)))
+
+    def canberra_distance(self, p):
+        """The Canberra Distance from self to point p.
+
+        Returns the weighted sum of horizontal and vertical distances to
+        point p.
+
+        Parameters
+        ==========
+
+        p : Point
+
+        Returns
+        =======
+
+        canberra_distance : The weighted sum of horizontal and vertical
+        distances to point p. The weight used is the sum of absolute values
+        of the coordinates.
+
+        Examples
+        ========
+
+        >>> from sympy import Point
+        >>> p1, p2 = Point(1, 1), Point(3, 3)
+        >>> p1.canberra_distance(p2)
+        1
+        >>> p1, p2 = Point(0, 0), Point(3, 3)
+        >>> p1.canberra_distance(p2)
+        2
+
+        Raises
+        ======
+
+        ValueError when both vectors are zero.
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point.distance
+
+        """
+
+        s, p = Point._normalize_dimension(self, Point(p))
+        if self.is_zero and p.is_zero:
+            raise ValueError("Cannot project to the zero vector.")
+        return Add(*((abs(a - b)/(abs(a) + abs(b))) for a, b in zip(s, p)))
+
+    @property
+    def unit(self):
+        """Return the Point that is in the same direction as `self`
+        and a distance of 1 from the origin"""
+        return self / abs(self)
+
+
+class Point2D(Point):
+    """A point in a 2-dimensional Euclidean space.
+
+    Parameters
+    ==========
+
+    coords
+        A sequence of 2 coordinate values.
+
+    Attributes
+    ==========
+
+    x
+    y
+    length
+
+    Raises
+    ======
+
+    TypeError
+        When trying to add or subtract points with different dimensions.
+        When trying to create a point with more than two dimensions.
+        When `intersection` is called with object other than a Point.
+
+    See Also
+    ========
+
+    sympy.geometry.line.Segment : Connects two Points
+
+    Examples
+    ========
+
+    >>> from sympy import Point2D
+    >>> from sympy.abc import x
+    >>> Point2D(1, 2)
+    Point2D(1, 2)
+    >>> Point2D([1, 2])
+    Point2D(1, 2)
+    >>> Point2D(0, x)
+    Point2D(0, x)
+
+    Floats are automatically converted to Rational unless the
+    evaluate flag is False:
+
+    >>> Point2D(0.5, 0.25)
+    Point2D(1/2, 1/4)
+    >>> Point2D(0.5, 0.25, evaluate=False)
+    Point2D(0.5, 0.25)
+
+    """
+
+    _ambient_dimension = 2
+
+    def __new__(cls, *args, _nocheck=False, **kwargs):
+        if not _nocheck:
+            kwargs['dim'] = 2
+            args = Point(*args, **kwargs)
+        return GeometryEntity.__new__(cls, *args)
+
+    def __contains__(self, item):
+        return item == self
+
+    @property
+    def bounds(self):
+        """Return a tuple (xmin, ymin, xmax, ymax) representing the bounding
+        rectangle for the geometric figure.
+
+        """
+
+        return (self.x, self.y, self.x, self.y)
+
+    def rotate(self, angle, pt=None):
+        """Rotate ``angle`` radians counterclockwise about Point ``pt``.
+
+        See Also
+        ========
+
+        translate, scale
+
+        Examples
+        ========
+
+        >>> from sympy import Point2D, pi
+        >>> t = Point2D(1, 0)
+        >>> t.rotate(pi/2)
+        Point2D(0, 1)
+        >>> t.rotate(pi/2, (2, 0))
+        Point2D(2, -1)
+
+        """
+        c = cos(angle)
+        s = sin(angle)
+
+        rv = self
+        if pt is not None:
+            pt = Point(pt, dim=2)
+            rv -= pt
+        x, y = rv.args
+        rv = Point(c*x - s*y, s*x + c*y)
+        if pt is not None:
+            rv += pt
+        return rv
+
+    def scale(self, x=1, y=1, pt=None):
+        """Scale the coordinates of the Point by multiplying by
+        ``x`` and ``y`` after subtracting ``pt`` -- default is (0, 0) --
+        and then adding ``pt`` back again (i.e. ``pt`` is the point of
+        reference for the scaling).
+
+        See Also
+        ========
+
+        rotate, translate
+
+        Examples
+        ========
+
+        >>> from sympy import Point2D
+        >>> t = Point2D(1, 1)
+        >>> t.scale(2)
+        Point2D(2, 1)
+        >>> t.scale(2, 2)
+        Point2D(2, 2)
+
+        """
+        if pt:
+            pt = Point(pt, dim=2)
+            return self.translate(*(-pt).args).scale(x, y).translate(*pt.args)
+        return Point(self.x*x, self.y*y)
+
+    def transform(self, matrix):
+        """Return the point after applying the transformation described
+        by the 3x3 Matrix, ``matrix``.
+
+        See Also
+        ========
+        sympy.geometry.point.Point2D.rotate
+        sympy.geometry.point.Point2D.scale
+        sympy.geometry.point.Point2D.translate
+        """
+        if not (matrix.is_Matrix and matrix.shape == (3, 3)):
+            raise ValueError("matrix must be a 3x3 matrix")
+        x, y = self.args
+        return Point(*(Matrix(1, 3, [x, y, 1])*matrix).tolist()[0][:2])
+
+    def translate(self, x=0, y=0):
+        """Shift the Point by adding x and y to the coordinates of the Point.
+
+        See Also
+        ========
+
+        sympy.geometry.point.Point2D.rotate, scale
+
+        Examples
+        ========
+
+        >>> from sympy import Point2D
+        >>> t = Point2D(0, 1)
+        >>> t.translate(2)
+        Point2D(2, 1)
+        >>> t.translate(2, 2)
+        Point2D(2, 3)
+        >>> t + Point2D(2, 2)
+        Point2D(2, 3)
+
+        """
+        return Point(self.x + x, self.y + y)
+
+    @property
+    def coordinates(self):
+        """
+        Returns the two coordinates of the Point.
+
+        Examples
+        ========
+
+        >>> from sympy import Point2D
+        >>> p = Point2D(0, 1)
+        >>> p.coordinates
+        (0, 1)
+        """
+        return self.args
+
+    @property
+    def x(self):
+        """
+        Returns the X coordinate of the Point.
+
+        Examples
+        ========
+
+        >>> from sympy import Point2D
+        >>> p = Point2D(0, 1)
+        >>> p.x
+        0
+        """
+        return self.args[0]
+
+    @property
+    def y(self):
+        """
+        Returns the Y coordinate of the Point.
+
+        Examples
+        ========
+
+        >>> from sympy import Point2D
+        >>> p = Point2D(0, 1)
+        >>> p.y
+        1
+        """
+        return self.args[1]
+
+class Point3D(Point):
+    """A point in a 3-dimensional Euclidean space.
+
+    Parameters
+    ==========
+
+    coords
+        A sequence of 3 coordinate values.
+
+    Attributes
+    ==========
+
+    x
+    y
+    z
+    length
+
+    Raises
+    ======
+
+    TypeError
+        When trying to add or subtract points with different dimensions.
+        When `intersection` is called with object other than a Point.
+
+    Examples
+    ========
+
+    >>> from sympy import Point3D
+    >>> from sympy.abc import x
+    >>> Point3D(1, 2, 3)
+    Point3D(1, 2, 3)
+    >>> Point3D([1, 2, 3])
+    Point3D(1, 2, 3)
+    >>> Point3D(0, x, 3)
+    Point3D(0, x, 3)
+
+    Floats are automatically converted to Rational unless the
+    evaluate flag is False:
+
+    >>> Point3D(0.5, 0.25, 2)
+    Point3D(1/2, 1/4, 2)
+    >>> Point3D(0.5, 0.25, 3, evaluate=False)
+    Point3D(0.5, 0.25, 3)
+
+    """
+
+    _ambient_dimension = 3
+
+    def __new__(cls, *args, _nocheck=False, **kwargs):
+        if not _nocheck:
+            kwargs['dim'] = 3
+            args = Point(*args, **kwargs)
+        return GeometryEntity.__new__(cls, *args)
+
+    def __contains__(self, item):
+        return item == self
+
+    @staticmethod
+    def are_collinear(*points):
+        """Is a sequence of points collinear?
+
+        Test whether or not a set of points are collinear. Returns True if
+        the set of points are collinear, or False otherwise.
+
+        Parameters
+        ==========
+
+        points : sequence of Point
+
+        Returns
+        =======
+
+        are_collinear : boolean
+
+        See Also
+        ========
+
+        sympy.geometry.line.Line3D
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D
+        >>> from sympy.abc import x
+        >>> p1, p2 = Point3D(0, 0, 0), Point3D(1, 1, 1)
+        >>> p3, p4, p5 = Point3D(2, 2, 2), Point3D(x, x, x), Point3D(1, 2, 6)
+        >>> Point3D.are_collinear(p1, p2, p3, p4)
+        True
+        >>> Point3D.are_collinear(p1, p2, p3, p5)
+        False
+        """
+        return Point.is_collinear(*points)
+
+    def direction_cosine(self, point):
+        """
+        Gives the direction cosine between 2 points
+
+        Parameters
+        ==========
+
+        p : Point3D
+
+        Returns
+        =======
+
+        list
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D
+        >>> p1 = Point3D(1, 2, 3)
+        >>> p1.direction_cosine(Point3D(2, 3, 5))
+        [sqrt(6)/6, sqrt(6)/6, sqrt(6)/3]
+        """
+        a = self.direction_ratio(point)
+        b = sqrt(Add(*(i**2 for i in a)))
+        return [(point.x - self.x) / b,(point.y - self.y) / b,
+                (point.z - self.z) / b]
+
+    def direction_ratio(self, point):
+        """
+        Gives the direction ratio between 2 points
+
+        Parameters
+        ==========
+
+        p : Point3D
+
+        Returns
+        =======
+
+        list
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D
+        >>> p1 = Point3D(1, 2, 3)
+        >>> p1.direction_ratio(Point3D(2, 3, 5))
+        [1, 1, 2]
+        """
+        return [(point.x - self.x),(point.y - self.y),(point.z - self.z)]
+
+    def intersection(self, other):
+        """The intersection between this point and another GeometryEntity.
+
+        Parameters
+        ==========
+
+        other : GeometryEntity or sequence of coordinates
+
+        Returns
+        =======
+
+        intersection : list of Points
+
+        Notes
+        =====
+
+        The return value will either be an empty list if there is no
+        intersection, otherwise it will contain this point.
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D
+        >>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(1, 1, 1), Point3D(0, 0, 0)
+        >>> p1.intersection(p2)
+        []
+        >>> p1.intersection(p3)
+        [Point3D(0, 0, 0)]
+
+        """
+        if not isinstance(other, GeometryEntity):
+            other = Point(other, dim=3)
+        if isinstance(other, Point3D):
+            if self == other:
+                return [self]
+            return []
+        return other.intersection(self)
+
+    def scale(self, x=1, y=1, z=1, pt=None):
+        """Scale the coordinates of the Point by multiplying by
+        ``x`` and ``y`` after subtracting ``pt`` -- default is (0, 0) --
+        and then adding ``pt`` back again (i.e. ``pt`` is the point of
+        reference for the scaling).
+
+        See Also
+        ========
+
+        translate
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D
+        >>> t = Point3D(1, 1, 1)
+        >>> t.scale(2)
+        Point3D(2, 1, 1)
+        >>> t.scale(2, 2)
+        Point3D(2, 2, 1)
+
+        """
+        if pt:
+            pt = Point3D(pt)
+            return self.translate(*(-pt).args).scale(x, y, z).translate(*pt.args)
+        return Point3D(self.x*x, self.y*y, self.z*z)
+
+    def transform(self, matrix):
+        """Return the point after applying the transformation described
+        by the 4x4 Matrix, ``matrix``.
+
+        See Also
+        ========
+        sympy.geometry.point.Point3D.scale
+        sympy.geometry.point.Point3D.translate
+        """
+        if not (matrix.is_Matrix and matrix.shape == (4, 4)):
+            raise ValueError("matrix must be a 4x4 matrix")
+        x, y, z = self.args
+        m = Transpose(matrix)
+        return Point3D(*(Matrix(1, 4, [x, y, z, 1])*m).tolist()[0][:3])
+
+    def translate(self, x=0, y=0, z=0):
+        """Shift the Point by adding x and y to the coordinates of the Point.
+
+        See Also
+        ========
+
+        scale
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D
+        >>> t = Point3D(0, 1, 1)
+        >>> t.translate(2)
+        Point3D(2, 1, 1)
+        >>> t.translate(2, 2)
+        Point3D(2, 3, 1)
+        >>> t + Point3D(2, 2, 2)
+        Point3D(2, 3, 3)
+
+        """
+        return Point3D(self.x + x, self.y + y, self.z + z)
+
+    @property
+    def coordinates(self):
+        """
+        Returns the three coordinates of the Point.
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D
+        >>> p = Point3D(0, 1, 2)
+        >>> p.coordinates
+        (0, 1, 2)
+        """
+        return self.args
+
+    @property
+    def x(self):
+        """
+        Returns the X coordinate of the Point.
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D
+        >>> p = Point3D(0, 1, 3)
+        >>> p.x
+        0
+        """
+        return self.args[0]
+
+    @property
+    def y(self):
+        """
+        Returns the Y coordinate of the Point.
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D
+        >>> p = Point3D(0, 1, 2)
+        >>> p.y
+        1
+        """
+        return self.args[1]
+
+    @property
+    def z(self):
+        """
+        Returns the Z coordinate of the Point.
+
+        Examples
+        ========
+
+        >>> from sympy import Point3D
+        >>> p = Point3D(0, 1, 1)
+        >>> p.z
+        1
+        """
+        return self.args[2]