Add files using upload-large-folder tool

lib/python3.12/site-packages/sympy/physics/control/__init__.py

@@ -0,0 +1,16 @@
+from .lti import (TransferFunction, Series, MIMOSeries, Parallel, MIMOParallel,
+    Feedback, MIMOFeedback, TransferFunctionMatrix, StateSpace, gbt, bilinear, forward_diff,
+    backward_diff, phase_margin, gain_margin)
+from .control_plots import (pole_zero_numerical_data, pole_zero_plot, step_response_numerical_data,
+    step_response_plot, impulse_response_numerical_data, impulse_response_plot, ramp_response_numerical_data,
+    ramp_response_plot, bode_magnitude_numerical_data, bode_phase_numerical_data, bode_magnitude_plot,
+    bode_phase_plot, bode_plot)
+
+__all__ = ['TransferFunction', 'Series', 'MIMOSeries', 'Parallel',
+    'MIMOParallel', 'Feedback', 'MIMOFeedback', 'TransferFunctionMatrix', 'StateSpace',
+    'gbt', 'bilinear', 'forward_diff', 'backward_diff', 'phase_margin', 'gain_margin',
+    'pole_zero_numerical_data', 'pole_zero_plot', 'step_response_numerical_data',
+    'step_response_plot', 'impulse_response_numerical_data', 'impulse_response_plot',
+    'ramp_response_numerical_data', 'ramp_response_plot',
+    'bode_magnitude_numerical_data', 'bode_phase_numerical_data',
+    'bode_magnitude_plot', 'bode_phase_plot', 'bode_plot']

lib/python3.12/site-packages/sympy/physics/control/control_plots.py

@@ -0,0 +1,978 @@
+from sympy.core.numbers import I, pi
+from sympy.functions.elementary.exponential import (exp, log)
+from sympy.polys.partfrac import apart
+from sympy.core.symbol import Dummy
+from sympy.external import import_module
+from sympy.functions import arg, Abs
+from sympy.integrals.laplace import _fast_inverse_laplace
+from sympy.physics.control.lti import SISOLinearTimeInvariant
+from sympy.plotting.series import LineOver1DRangeSeries
+from sympy.polys.polytools import Poly
+from sympy.printing.latex import latex
+
+__all__ = ['pole_zero_numerical_data', 'pole_zero_plot',
+    'step_response_numerical_data', 'step_response_plot',
+    'impulse_response_numerical_data', 'impulse_response_plot',
+    'ramp_response_numerical_data', 'ramp_response_plot',
+    'bode_magnitude_numerical_data', 'bode_phase_numerical_data',
+    'bode_magnitude_plot', 'bode_phase_plot', 'bode_plot']
+
+matplotlib = import_module(
+        'matplotlib', import_kwargs={'fromlist': ['pyplot']},
+        catch=(RuntimeError,))
+
+numpy = import_module('numpy')
+
+if matplotlib:
+    plt = matplotlib.pyplot
+
+if numpy:
+    np = numpy  # Matplotlib already has numpy as a compulsory dependency. No need to install it separately.
+
+
+def _check_system(system):
+    """Function to check whether the dynamical system passed for plots is
+    compatible or not."""
+    if not isinstance(system, SISOLinearTimeInvariant):
+        raise NotImplementedError("Only SISO LTI systems are currently supported.")
+    sys = system.to_expr()
+    len_free_symbols = len(sys.free_symbols)
+    if len_free_symbols > 1:
+        raise ValueError("Extra degree of freedom found. Make sure"
+            " that there are no free symbols in the dynamical system other"
+            " than the variable of Laplace transform.")
+    if sys.has(exp):
+        # Should test that exp is not part of a constant, in which case
+        # no exception is required, compare exp(s) with s*exp(1)
+        raise NotImplementedError("Time delay terms are not supported.")
+
+
+def pole_zero_numerical_data(system):
+    """
+    Returns the numerical data of poles and zeros of the system.
+    It is internally used by ``pole_zero_plot`` to get the data
+    for plotting poles and zeros. Users can use this data to further
+    analyse the dynamics of the system or plot using a different
+    backend/plotting-module.
+
+    Parameters
+    ==========
+
+    system : SISOLinearTimeInvariant
+        The system for which the pole-zero data is to be computed.
+
+    Returns
+    =======
+
+    tuple : (zeros, poles)
+        zeros = Zeros of the system. NumPy array of complex numbers.
+        poles = Poles of the system. NumPy array of complex numbers.
+
+    Raises
+    ======
+
+    NotImplementedError
+        When a SISO LTI system is not passed.
+
+        When time delay terms are present in the system.
+
+    ValueError
+        When more than one free symbol is present in the system.
+        The only variable in the transfer function should be
+        the variable of the Laplace transform.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import s
+    >>> from sympy.physics.control.lti import TransferFunction
+    >>> from sympy.physics.control.control_plots import pole_zero_numerical_data
+    >>> tf1 = TransferFunction(s**2 + 1, s**4 + 4*s**3 + 6*s**2 + 5*s + 2, s)
+    >>> pole_zero_numerical_data(tf1)   # doctest: +SKIP
+    ([-0.+1.j  0.-1.j], [-2. +0.j        -0.5+0.8660254j -0.5-0.8660254j -1. +0.j       ])
+
+    See Also
+    ========
+
+    pole_zero_plot
+
+    """
+    _check_system(system)
+    system = system.doit()  # Get the equivalent TransferFunction object.
+
+    num_poly = Poly(system.num, system.var).all_coeffs()
+    den_poly = Poly(system.den, system.var).all_coeffs()
+
+    num_poly = np.array(num_poly, dtype=np.complex128)
+    den_poly = np.array(den_poly, dtype=np.complex128)
+
+    zeros = np.roots(num_poly)
+    poles = np.roots(den_poly)
+
+    return zeros, poles
+
+
+def pole_zero_plot(system, pole_color='blue', pole_markersize=10,
+    zero_color='orange', zero_markersize=7, grid=True, show_axes=True,
+    show=True, **kwargs):
+    r"""
+    Returns the Pole-Zero plot (also known as PZ Plot or PZ Map) of a system.
+
+    A Pole-Zero plot is a graphical representation of a system's poles and
+    zeros. It is plotted on a complex plane, with circular markers representing
+    the system's zeros and 'x' shaped markers representing the system's poles.
+
+    Parameters
+    ==========
+
+    system : SISOLinearTimeInvariant type systems
+        The system for which the pole-zero plot is to be computed.
+    pole_color : str, tuple, optional
+        The color of the pole points on the plot. Default color
+        is blue. The color can be provided as a matplotlib color string,
+        or a 3-tuple of floats each in the 0-1 range.
+    pole_markersize : Number, optional
+        The size of the markers used to mark the poles in the plot.
+        Default pole markersize is 10.
+    zero_color : str, tuple, optional
+        The color of the zero points on the plot. Default color
+        is orange. The color can be provided as a matplotlib color string,
+        or a 3-tuple of floats each in the 0-1 range.
+    zero_markersize : Number, optional
+        The size of the markers used to mark the zeros in the plot.
+        Default zero markersize is 7.
+    grid : boolean, optional
+        If ``True``, the plot will have a grid. Defaults to True.
+    show_axes : boolean, optional
+        If ``True``, the coordinate axes will be shown. Defaults to False.
+    show : boolean, optional
+        If ``True``, the plot will be displayed otherwise
+        the equivalent matplotlib ``plot`` object will be returned.
+        Defaults to True.
+
+    Examples
+    ========
+
+    .. plot::
+        :context: close-figs
+        :format: doctest
+        :include-source: True
+
+        >>> from sympy.abc import s
+        >>> from sympy.physics.control.lti import TransferFunction
+        >>> from sympy.physics.control.control_plots import pole_zero_plot
+        >>> tf1 = TransferFunction(s**2 + 1, s**4 + 4*s**3 + 6*s**2 + 5*s + 2, s)
+        >>> pole_zero_plot(tf1)   # doctest: +SKIP
+
+    See Also
+    ========
+
+    pole_zero_numerical_data
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Pole%E2%80%93zero_plot
+
+    """
+    zeros, poles = pole_zero_numerical_data(system)
+
+    zero_real = np.real(zeros)
+    zero_imag = np.imag(zeros)
+
+    pole_real = np.real(poles)
+    pole_imag = np.imag(poles)
+
+    plt.plot(pole_real, pole_imag, 'x', mfc='none',
+        markersize=pole_markersize, color=pole_color)
+    plt.plot(zero_real, zero_imag, 'o', markersize=zero_markersize,
+        color=zero_color)
+    plt.xlabel('Real Axis')
+    plt.ylabel('Imaginary Axis')
+    plt.title(f'Poles and Zeros of ${latex(system)}$', pad=20)
+
+    if grid:
+        plt.grid()
+    if show_axes:
+        plt.axhline(0, color='black')
+        plt.axvline(0, color='black')
+    if show:
+        plt.show()
+        return
+
+    return plt
+
+
+def step_response_numerical_data(system, prec=8, lower_limit=0,
+    upper_limit=10, **kwargs):
+    """
+    Returns the numerical values of the points in the step response plot
+    of a SISO continuous-time system. By default, adaptive sampling
+    is used. If the user wants to instead get an uniformly
+    sampled response, then ``adaptive`` kwarg should be passed ``False``
+    and ``n`` must be passed as additional kwargs.
+    Refer to the parameters of class :class:`sympy.plotting.series.LineOver1DRangeSeries`
+    for more details.
+
+    Parameters
+    ==========
+
+    system : SISOLinearTimeInvariant
+        The system for which the unit step response data is to be computed.
+    prec : int, optional
+        The decimal point precision for the point coordinate values.
+        Defaults to 8.
+    lower_limit : Number, optional
+        The lower limit of the plot range. Defaults to 0.
+    upper_limit : Number, optional
+        The upper limit of the plot range. Defaults to 10.
+    kwargs :
+        Additional keyword arguments are passed to the underlying
+        :class:`sympy.plotting.series.LineOver1DRangeSeries` class.
+
+    Returns
+    =======
+
+    tuple : (x, y)
+        x = Time-axis values of the points in the step response. NumPy array.
+        y = Amplitude-axis values of the points in the step response. NumPy array.
+
+    Raises
+    ======
+
+    NotImplementedError
+        When a SISO LTI system is not passed.
+
+        When time delay terms are present in the system.
+
+    ValueError
+        When more than one free symbol is present in the system.
+        The only variable in the transfer function should be
+        the variable of the Laplace transform.
+
+        When ``lower_limit`` parameter is less than 0.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import s
+    >>> from sympy.physics.control.lti import TransferFunction
+    >>> from sympy.physics.control.control_plots import step_response_numerical_data
+    >>> tf1 = TransferFunction(s, s**2 + 5*s + 8, s)
+    >>> step_response_numerical_data(tf1)   # doctest: +SKIP
+    ([0.0, 0.025413462339411542, 0.0484508722725343, ... , 9.670250533855183, 9.844291913708725, 10.0],
+    [0.0, 0.023844582399907256, 0.042894276802320226, ..., 6.828770759094287e-12, 6.456457160755703e-12])
+
+    See Also
+    ========
+
+    step_response_plot
+
+    """
+    if lower_limit < 0:
+        raise ValueError("Lower limit of time must be greater "
+            "than or equal to zero.")
+    _check_system(system)
+    _x = Dummy("x")
+    expr = system.to_expr()/(system.var)
+    expr = apart(expr, system.var, full=True)
+    _y = _fast_inverse_laplace(expr, system.var, _x).evalf(prec)
+    return LineOver1DRangeSeries(_y, (_x, lower_limit, upper_limit),
+        **kwargs).get_points()
+
+
+def step_response_plot(system, color='b', prec=8, lower_limit=0,
+    upper_limit=10, show_axes=False, grid=True, show=True, **kwargs):
+    r"""
+    Returns the unit step response of a continuous-time system. It is
+    the response of the system when the input signal is a step function.
+
+    Parameters
+    ==========
+
+    system : SISOLinearTimeInvariant type
+        The LTI SISO system for which the Step Response is to be computed.
+    color : str, tuple, optional
+        The color of the line. Default is Blue.
+    show : boolean, optional
+        If ``True``, the plot will be displayed otherwise
+        the equivalent matplotlib ``plot`` object will be returned.
+        Defaults to True.
+    lower_limit : Number, optional
+        The lower limit of the plot range. Defaults to 0.
+    upper_limit : Number, optional
+        The upper limit of the plot range. Defaults to 10.
+    prec : int, optional
+        The decimal point precision for the point coordinate values.
+        Defaults to 8.
+    show_axes : boolean, optional
+        If ``True``, the coordinate axes will be shown. Defaults to False.
+    grid : boolean, optional
+        If ``True``, the plot will have a grid. Defaults to True.
+
+    Examples
+    ========
+
+    .. plot::
+        :context: close-figs
+        :format: doctest
+        :include-source: True
+
+        >>> from sympy.abc import s
+        >>> from sympy.physics.control.lti import TransferFunction
+        >>> from sympy.physics.control.control_plots import step_response_plot
+        >>> tf1 = TransferFunction(8*s**2 + 18*s + 32, s**3 + 6*s**2 + 14*s + 24, s)
+        >>> step_response_plot(tf1)   # doctest: +SKIP
+
+    See Also
+    ========
+
+    impulse_response_plot, ramp_response_plot
+
+    References
+    ==========
+
+    .. [1] https://www.mathworks.com/help/control/ref/lti.step.html
+
+    """
+    x, y = step_response_numerical_data(system, prec=prec,
+        lower_limit=lower_limit, upper_limit=upper_limit, **kwargs)
+    plt.plot(x, y, color=color)
+    plt.xlabel('Time (s)')
+    plt.ylabel('Amplitude')
+    plt.title(f'Unit Step Response of ${latex(system)}$', pad=20)
+
+    if grid:
+        plt.grid()
+    if show_axes:
+        plt.axhline(0, color='black')
+        plt.axvline(0, color='black')
+    if show:
+        plt.show()
+        return
+
+    return plt
+
+
+def impulse_response_numerical_data(system, prec=8, lower_limit=0,
+    upper_limit=10, **kwargs):
+    """
+    Returns the numerical values of the points in the impulse response plot
+    of a SISO continuous-time system. By default, adaptive sampling
+    is used. If the user wants to instead get an uniformly
+    sampled response, then ``adaptive`` kwarg should be passed ``False``
+    and ``n`` must be passed as additional kwargs.
+    Refer to the parameters of class :class:`sympy.plotting.series.LineOver1DRangeSeries`
+    for more details.
+
+    Parameters
+    ==========
+
+    system : SISOLinearTimeInvariant
+        The system for which the impulse response data is to be computed.
+    prec : int, optional
+        The decimal point precision for the point coordinate values.
+        Defaults to 8.
+    lower_limit : Number, optional
+        The lower limit of the plot range. Defaults to 0.
+    upper_limit : Number, optional
+        The upper limit of the plot range. Defaults to 10.
+    kwargs :
+        Additional keyword arguments are passed to the underlying
+        :class:`sympy.plotting.series.LineOver1DRangeSeries` class.
+
+    Returns
+    =======
+
+    tuple : (x, y)
+        x = Time-axis values of the points in the impulse response. NumPy array.
+        y = Amplitude-axis values of the points in the impulse response. NumPy array.
+
+    Raises
+    ======
+
+    NotImplementedError
+        When a SISO LTI system is not passed.
+
+        When time delay terms are present in the system.
+
+    ValueError
+        When more than one free symbol is present in the system.
+        The only variable in the transfer function should be
+        the variable of the Laplace transform.
+
+        When ``lower_limit`` parameter is less than 0.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import s
+    >>> from sympy.physics.control.lti import TransferFunction
+    >>> from sympy.physics.control.control_plots import impulse_response_numerical_data
+    >>> tf1 = TransferFunction(s, s**2 + 5*s + 8, s)
+    >>> impulse_response_numerical_data(tf1)   # doctest: +SKIP
+    ([0.0, 0.06616480200395854,... , 9.854500743565858, 10.0],
+    [0.9999999799999999, 0.7042848373025861,...,7.170748906965121e-13, -5.1901263495547205e-12])
+
+    See Also
+    ========
+
+    impulse_response_plot
+
+    """
+    if lower_limit < 0:
+        raise ValueError("Lower limit of time must be greater "
+            "than or equal to zero.")
+    _check_system(system)
+    _x = Dummy("x")
+    expr = system.to_expr()
+    expr = apart(expr, system.var, full=True)
+    _y = _fast_inverse_laplace(expr, system.var, _x).evalf(prec)
+    return LineOver1DRangeSeries(_y, (_x, lower_limit, upper_limit),
+        **kwargs).get_points()
+
+
+def impulse_response_plot(system, color='b', prec=8, lower_limit=0,
+    upper_limit=10, show_axes=False, grid=True, show=True, **kwargs):
+    r"""
+    Returns the unit impulse response (Input is the Dirac-Delta Function) of a
+    continuous-time system.
+
+    Parameters
+    ==========
+
+    system : SISOLinearTimeInvariant type
+        The LTI SISO system for which the Impulse Response is to be computed.
+    color : str, tuple, optional
+        The color of the line. Default is Blue.
+    show : boolean, optional
+        If ``True``, the plot will be displayed otherwise
+        the equivalent matplotlib ``plot`` object will be returned.
+        Defaults to True.
+    lower_limit : Number, optional
+        The lower limit of the plot range. Defaults to 0.
+    upper_limit : Number, optional
+        The upper limit of the plot range. Defaults to 10.
+    prec : int, optional
+        The decimal point precision for the point coordinate values.
+        Defaults to 8.
+    show_axes : boolean, optional
+        If ``True``, the coordinate axes will be shown. Defaults to False.
+    grid : boolean, optional
+        If ``True``, the plot will have a grid. Defaults to True.
+
+    Examples
+    ========
+
+    .. plot::
+        :context: close-figs
+        :format: doctest
+        :include-source: True
+
+        >>> from sympy.abc import s
+        >>> from sympy.physics.control.lti import TransferFunction
+        >>> from sympy.physics.control.control_plots import impulse_response_plot
+        >>> tf1 = TransferFunction(8*s**2 + 18*s + 32, s**3 + 6*s**2 + 14*s + 24, s)
+        >>> impulse_response_plot(tf1)   # doctest: +SKIP
+
+    See Also
+    ========
+
+    step_response_plot, ramp_response_plot
+
+    References
+    ==========
+
+    .. [1] https://www.mathworks.com/help/control/ref/dynamicsystem.impulse.html
+
+    """
+    x, y = impulse_response_numerical_data(system, prec=prec,
+        lower_limit=lower_limit, upper_limit=upper_limit, **kwargs)
+    plt.plot(x, y, color=color)
+    plt.xlabel('Time (s)')
+    plt.ylabel('Amplitude')
+    plt.title(f'Impulse Response of ${latex(system)}$', pad=20)
+
+    if grid:
+        plt.grid()
+    if show_axes:
+        plt.axhline(0, color='black')
+        plt.axvline(0, color='black')
+    if show:
+        plt.show()
+        return
+
+    return plt
+
+
+def ramp_response_numerical_data(system, slope=1, prec=8,
+    lower_limit=0, upper_limit=10, **kwargs):
+    """
+    Returns the numerical values of the points in the ramp response plot
+    of a SISO continuous-time system. By default, adaptive sampling
+    is used. If the user wants to instead get an uniformly
+    sampled response, then ``adaptive`` kwarg should be passed ``False``
+    and ``n`` must be passed as additional kwargs.
+    Refer to the parameters of class :class:`sympy.plotting.series.LineOver1DRangeSeries`
+    for more details.
+
+    Parameters
+    ==========
+
+    system : SISOLinearTimeInvariant
+        The system for which the ramp response data is to be computed.
+    slope : Number, optional
+        The slope of the input ramp function. Defaults to 1.
+    prec : int, optional
+        The decimal point precision for the point coordinate values.
+        Defaults to 8.
+    lower_limit : Number, optional
+        The lower limit of the plot range. Defaults to 0.
+    upper_limit : Number, optional
+        The upper limit of the plot range. Defaults to 10.
+    kwargs :
+        Additional keyword arguments are passed to the underlying
+        :class:`sympy.plotting.series.LineOver1DRangeSeries` class.
+
+    Returns
+    =======
+
+    tuple : (x, y)
+        x = Time-axis values of the points in the ramp response plot. NumPy array.
+        y = Amplitude-axis values of the points in the ramp response plot. NumPy array.
+
+    Raises
+    ======
+
+    NotImplementedError
+        When a SISO LTI system is not passed.
+
+        When time delay terms are present in the system.
+
+    ValueError
+        When more than one free symbol is present in the system.
+        The only variable in the transfer function should be
+        the variable of the Laplace transform.
+
+        When ``lower_limit`` parameter is less than 0.
+
+        When ``slope`` is negative.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import s
+    >>> from sympy.physics.control.lti import TransferFunction
+    >>> from sympy.physics.control.control_plots import ramp_response_numerical_data
+    >>> tf1 = TransferFunction(s, s**2 + 5*s + 8, s)
+    >>> ramp_response_numerical_data(tf1)   # doctest: +SKIP
+    (([0.0, 0.12166980856813935,..., 9.861246379582118, 10.0],
+    [1.4504508011325967e-09, 0.006046440489058766,..., 0.12499999999568202, 0.12499999999661349]))
+
+    See Also
+    ========
+
+    ramp_response_plot
+
+    """
+    if slope < 0:
+        raise ValueError("Slope must be greater than or equal"
+            " to zero.")
+    if lower_limit < 0:
+        raise ValueError("Lower limit of time must be greater "
+            "than or equal to zero.")
+    _check_system(system)
+    _x = Dummy("x")
+    expr = (slope*system.to_expr())/((system.var)**2)
+    expr = apart(expr, system.var, full=True)
+    _y = _fast_inverse_laplace(expr, system.var, _x).evalf(prec)
+    return LineOver1DRangeSeries(_y, (_x, lower_limit, upper_limit),
+        **kwargs).get_points()
+
+
+def ramp_response_plot(system, slope=1, color='b', prec=8, lower_limit=0,
+    upper_limit=10, show_axes=False, grid=True, show=True, **kwargs):
+    r"""
+    Returns the ramp response of a continuous-time system.
+
+    Ramp function is defined as the straight line
+    passing through origin ($f(x) = mx$). The slope of
+    the ramp function can be varied by the user and
+    the default value is 1.
+
+    Parameters
+    ==========
+
+    system : SISOLinearTimeInvariant type
+        The LTI SISO system for which the Ramp Response is to be computed.
+    slope : Number, optional
+        The slope of the input ramp function. Defaults to 1.
+    color : str, tuple, optional
+        The color of the line. Default is Blue.
+    show : boolean, optional
+        If ``True``, the plot will be displayed otherwise
+        the equivalent matplotlib ``plot`` object will be returned.
+        Defaults to True.
+    lower_limit : Number, optional
+        The lower limit of the plot range. Defaults to 0.
+    upper_limit : Number, optional
+        The upper limit of the plot range. Defaults to 10.
+    prec : int, optional
+        The decimal point precision for the point coordinate values.
+        Defaults to 8.
+    show_axes : boolean, optional
+        If ``True``, the coordinate axes will be shown. Defaults to False.
+    grid : boolean, optional
+        If ``True``, the plot will have a grid. Defaults to True.
+
+    Examples
+    ========
+
+    .. plot::
+        :context: close-figs
+        :format: doctest
+        :include-source: True
+
+        >>> from sympy.abc import s
+        >>> from sympy.physics.control.lti import TransferFunction
+        >>> from sympy.physics.control.control_plots import ramp_response_plot
+        >>> tf1 = TransferFunction(s, (s+4)*(s+8), s)
+        >>> ramp_response_plot(tf1, upper_limit=2)   # doctest: +SKIP
+
+    See Also
+    ========
+
+    step_response_plot, impulse_response_plot
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Ramp_function
+
+    """
+    x, y = ramp_response_numerical_data(system, slope=slope, prec=prec,
+        lower_limit=lower_limit, upper_limit=upper_limit, **kwargs)
+    plt.plot(x, y, color=color)
+    plt.xlabel('Time (s)')
+    plt.ylabel('Amplitude')
+    plt.title(f'Ramp Response of ${latex(system)}$ [Slope = {slope}]', pad=20)
+
+    if grid:
+        plt.grid()
+    if show_axes:
+        plt.axhline(0, color='black')
+        plt.axvline(0, color='black')
+    if show:
+        plt.show()
+        return
+
+    return plt
+
+
+def bode_magnitude_numerical_data(system, initial_exp=-5, final_exp=5, freq_unit='rad/sec', **kwargs):
+    """
+    Returns the numerical data of the Bode magnitude plot of the system.
+    It is internally used by ``bode_magnitude_plot`` to get the data
+    for plotting Bode magnitude plot. Users can use this data to further
+    analyse the dynamics of the system or plot using a different
+    backend/plotting-module.
+
+    Parameters
+    ==========
+
+    system : SISOLinearTimeInvariant
+        The system for which the data is to be computed.
+    initial_exp : Number, optional
+        The initial exponent of 10 of the semilog plot. Defaults to -5.
+    final_exp : Number, optional
+        The final exponent of 10 of the semilog plot. Defaults to 5.
+    freq_unit : string, optional
+        User can choose between ``'rad/sec'`` (radians/second) and ``'Hz'`` (Hertz) as frequency units.
+
+    Returns
+    =======
+
+    tuple : (x, y)
+        x = x-axis values of the Bode magnitude plot.
+        y = y-axis values of the Bode magnitude plot.
+
+    Raises
+    ======
+
+    NotImplementedError
+        When a SISO LTI system is not passed.
+
+        When time delay terms are present in the system.
+
+    ValueError
+        When more than one free symbol is present in the system.
+        The only variable in the transfer function should be
+        the variable of the Laplace transform.
+
+        When incorrect frequency units are given as input.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import s
+    >>> from sympy.physics.control.lti import TransferFunction
+    >>> from sympy.physics.control.control_plots import bode_magnitude_numerical_data
+    >>> tf1 = TransferFunction(s**2 + 1, s**4 + 4*s**3 + 6*s**2 + 5*s + 2, s)
+    >>> bode_magnitude_numerical_data(tf1)   # doctest: +SKIP
+    ([1e-05, 1.5148378120533502e-05,..., 68437.36188804005, 100000.0],
+    [-6.020599914256786, -6.0205999155219505,..., -193.4117304087953, -200.00000000260573])
+
+    See Also
+    ========
+
+    bode_magnitude_plot, bode_phase_numerical_data
+
+    """
+    _check_system(system)
+    expr = system.to_expr()
+    freq_units = ('rad/sec', 'Hz')
+    if freq_unit not in freq_units:
+        raise ValueError('Only "rad/sec" and "Hz" are accepted frequency units.')
+
+    _w = Dummy("w", real=True)
+    if freq_unit == 'Hz':
+        repl = I*_w*2*pi
+    else:
+        repl = I*_w
+    w_expr = expr.subs({system.var: repl})
+
+    mag = 20*log(Abs(w_expr), 10)
+
+    x, y = LineOver1DRangeSeries(mag,
+        (_w, 10**initial_exp, 10**final_exp), xscale='log', **kwargs).get_points()
+
+    return x, y
+
+
+def bode_magnitude_plot(system, initial_exp=-5, final_exp=5,
+    color='b', show_axes=False, grid=True, show=True, freq_unit='rad/sec', **kwargs):
+    r"""
+    Returns the Bode magnitude plot of a continuous-time system.
+
+    See ``bode_plot`` for all the parameters.
+    """
+    x, y = bode_magnitude_numerical_data(system, initial_exp=initial_exp,
+        final_exp=final_exp, freq_unit=freq_unit)
+    plt.plot(x, y, color=color, **kwargs)
+    plt.xscale('log')
+
+
+    plt.xlabel('Frequency (%s) [Log Scale]' % freq_unit)
+    plt.ylabel('Magnitude (dB)')
+    plt.title(f'Bode Plot (Magnitude) of ${latex(system)}$', pad=20)
+
+    if grid:
+        plt.grid(True)
+    if show_axes:
+        plt.axhline(0, color='black')
+        plt.axvline(0, color='black')
+    if show:
+        plt.show()
+        return
+
+    return plt
+
+
+def bode_phase_numerical_data(system, initial_exp=-5, final_exp=5, freq_unit='rad/sec', phase_unit='rad', phase_unwrap = True, **kwargs):
+    """
+    Returns the numerical data of the Bode phase plot of the system.
+    It is internally used by ``bode_phase_plot`` to get the data
+    for plotting Bode phase plot. Users can use this data to further
+    analyse the dynamics of the system or plot using a different
+    backend/plotting-module.
+
+    Parameters
+    ==========
+
+    system : SISOLinearTimeInvariant
+        The system for which the Bode phase plot data is to be computed.
+    initial_exp : Number, optional
+        The initial exponent of 10 of the semilog plot. Defaults to -5.
+    final_exp : Number, optional
+        The final exponent of 10 of the semilog plot. Defaults to 5.
+    freq_unit : string, optional
+        User can choose between ``'rad/sec'`` (radians/second) and '``'Hz'`` (Hertz) as frequency units.
+    phase_unit : string, optional
+        User can choose between ``'rad'`` (radians) and ``'deg'`` (degree) as phase units.
+    phase_unwrap : bool, optional
+        Set to ``True`` by default.
+
+    Returns
+    =======
+
+    tuple : (x, y)
+        x = x-axis values of the Bode phase plot.
+        y = y-axis values of the Bode phase plot.
+
+    Raises
+    ======
+
+    NotImplementedError
+        When a SISO LTI system is not passed.
+
+        When time delay terms are present in the system.
+
+    ValueError
+        When more than one free symbol is present in the system.
+        The only variable in the transfer function should be
+        the variable of the Laplace transform.
+
+        When incorrect frequency or phase units are given as input.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import s
+    >>> from sympy.physics.control.lti import TransferFunction
+    >>> from sympy.physics.control.control_plots import bode_phase_numerical_data
+    >>> tf1 = TransferFunction(s**2 + 1, s**4 + 4*s**3 + 6*s**2 + 5*s + 2, s)
+    >>> bode_phase_numerical_data(tf1)   # doctest: +SKIP
+    ([1e-05, 1.4472354033813751e-05, 2.035581932165858e-05,..., 47577.3248186011, 67884.09326036123, 100000.0],
+    [-2.5000000000291665e-05, -3.6180885085e-05, -5.08895483066e-05,...,-3.1415085799262523, -3.14155265358979])
+
+    See Also
+    ========
+
+    bode_magnitude_plot, bode_phase_numerical_data
+
+    """
+    _check_system(system)
+    expr = system.to_expr()
+    freq_units = ('rad/sec', 'Hz')
+    phase_units = ('rad', 'deg')
+    if freq_unit not in freq_units:
+        raise ValueError('Only "rad/sec" and "Hz" are accepted frequency units.')
+    if phase_unit not in phase_units:
+        raise ValueError('Only "rad" and "deg" are accepted phase units.')
+
+    _w = Dummy("w", real=True)
+    if freq_unit == 'Hz':
+        repl = I*_w*2*pi
+    else:
+        repl = I*_w
+    w_expr = expr.subs({system.var: repl})
+
+    if phase_unit == 'deg':
+        phase = arg(w_expr)*180/pi
+    else:
+        phase = arg(w_expr)
+
+    x, y = LineOver1DRangeSeries(phase,
+        (_w, 10**initial_exp, 10**final_exp), xscale='log', **kwargs).get_points()
+
+    half = None
+    if phase_unwrap:
+        if(phase_unit == 'rad'):
+            half = pi
+        elif(phase_unit == 'deg'):
+            half = 180
+    if half:
+        unit = 2*half
+        for i in range(1, len(y)):
+            diff = y[i] - y[i - 1]
+            if diff > half:      # Jump from -half to half
+                y[i] = (y[i] - unit)
+            elif diff < -half:   # Jump from half to -half
+                y[i] = (y[i] + unit)
+
+    return x, y
+
+
+def bode_phase_plot(system, initial_exp=-5, final_exp=5,
+    color='b', show_axes=False, grid=True, show=True, freq_unit='rad/sec', phase_unit='rad', phase_unwrap=True, **kwargs):
+    r"""
+    Returns the Bode phase plot of a continuous-time system.
+
+    See ``bode_plot`` for all the parameters.
+    """
+    x, y = bode_phase_numerical_data(system, initial_exp=initial_exp,
+        final_exp=final_exp, freq_unit=freq_unit, phase_unit=phase_unit, phase_unwrap=phase_unwrap)
+    plt.plot(x, y, color=color, **kwargs)
+    plt.xscale('log')
+
+    plt.xlabel('Frequency (%s) [Log Scale]' % freq_unit)
+    plt.ylabel('Phase (%s)' % phase_unit)
+    plt.title(f'Bode Plot (Phase) of ${latex(system)}$', pad=20)
+
+    if grid:
+        plt.grid(True)
+    if show_axes:
+        plt.axhline(0, color='black')
+        plt.axvline(0, color='black')
+    if show:
+        plt.show()
+        return
+
+    return plt
+
+
+def bode_plot(system, initial_exp=-5, final_exp=5,
+    grid=True, show_axes=False, show=True, freq_unit='rad/sec', phase_unit='rad', phase_unwrap=True, **kwargs):
+    r"""
+    Returns the Bode phase and magnitude plots of a continuous-time system.
+
+    Parameters
+    ==========
+
+    system : SISOLinearTimeInvariant type
+        The LTI SISO system for which the Bode Plot is to be computed.
+    initial_exp : Number, optional
+        The initial exponent of 10 of the semilog plot. Defaults to -5.
+    final_exp : Number, optional
+        The final exponent of 10 of the semilog plot. Defaults to 5.
+    show : boolean, optional
+        If ``True``, the plot will be displayed otherwise
+        the equivalent matplotlib ``plot`` object will be returned.
+        Defaults to True.
+    prec : int, optional
+        The decimal point precision for the point coordinate values.
+        Defaults to 8.
+    grid : boolean, optional
+        If ``True``, the plot will have a grid. Defaults to True.
+    show_axes : boolean, optional
+        If ``True``, the coordinate axes will be shown. Defaults to False.
+    freq_unit : string, optional
+        User can choose between ``'rad/sec'`` (radians/second) and ``'Hz'`` (Hertz) as frequency units.
+    phase_unit : string, optional
+        User can choose between ``'rad'`` (radians) and ``'deg'`` (degree) as phase units.
+
+    Examples
+    ========
+
+    .. plot::
+        :context: close-figs
+        :format: doctest
+        :include-source: True
+
+        >>> from sympy.abc import s
+        >>> from sympy.physics.control.lti import TransferFunction
+        >>> from sympy.physics.control.control_plots import bode_plot
+        >>> tf1 = TransferFunction(1*s**2 + 0.1*s + 7.5, 1*s**4 + 0.12*s**3 + 9*s**2, s)
+        >>> bode_plot(tf1, initial_exp=0.2, final_exp=0.7)   # doctest: +SKIP
+
+    See Also
+    ========
+
+    bode_magnitude_plot, bode_phase_plot
+
+    """
+    plt.subplot(211)
+    mag = bode_magnitude_plot(system, initial_exp=initial_exp, final_exp=final_exp,
+        show=False, grid=grid, show_axes=show_axes,
+        freq_unit=freq_unit, **kwargs)
+    mag.title(f'Bode Plot of ${latex(system)}$', pad=20)
+    mag.xlabel(None)
+    plt.subplot(212)
+    bode_phase_plot(system, initial_exp=initial_exp, final_exp=final_exp,
+        show=False, grid=grid, show_axes=show_axes, freq_unit=freq_unit, phase_unit=phase_unit, phase_unwrap=phase_unwrap, **kwargs).title(None)
+
+    if show:
+        plt.show()
+        return
+
+    return plt

lib/python3.12/site-packages/sympy/physics/control/tests/test_control_plots.py

@@ -0,0 +1,299 @@
+from math import isclose
+from sympy.core.numbers import I
+from sympy.core.symbol import Dummy
+from sympy.functions.elementary.complexes import (Abs, arg)
+from sympy.functions.elementary.exponential import log
+from sympy.abc import s, p, a
+from sympy.external import import_module
+from sympy.physics.control.control_plots import \
+    (pole_zero_numerical_data, pole_zero_plot, step_response_numerical_data,
+    step_response_plot, impulse_response_numerical_data,
+    impulse_response_plot, ramp_response_numerical_data,
+    ramp_response_plot, bode_magnitude_numerical_data,
+    bode_phase_numerical_data, bode_plot)
+from sympy.physics.control.lti import (TransferFunction,
+    Series, Parallel, TransferFunctionMatrix)
+from sympy.testing.pytest import raises, skip
+
+matplotlib = import_module(
+        'matplotlib', import_kwargs={'fromlist': ['pyplot']},
+        catch=(RuntimeError,))
+
+numpy = import_module('numpy')
+
+tf1 = TransferFunction(1, p**2 + 0.5*p + 2, p)
+tf2 = TransferFunction(p, 6*p**2 + 3*p + 1, p)
+tf3 = TransferFunction(p, p**3 - 1, p)
+tf4 = TransferFunction(10, p**3, p)
+tf5 = TransferFunction(5, s**2 + 2*s + 10, s)
+tf6 = TransferFunction(1, 1, s)
+tf7 = TransferFunction(4*s*3 + 9*s**2 + 0.1*s + 11, 8*s**6 + 9*s**4 + 11, s)
+tf8 = TransferFunction(5, s**2 + (2+I)*s + 10, s)
+
+ser1 = Series(tf4, TransferFunction(1, p - 5, p))
+ser2 = Series(tf3, TransferFunction(p, p + 2, p))
+
+par1 = Parallel(tf1, tf2)
+
+
+def _to_tuple(a, b):
+    return tuple(a), tuple(b)
+
+def _trim_tuple(a, b):
+    a, b = _to_tuple(a, b)
+    return tuple(a[0: 2] + a[len(a)//2 : len(a)//2 + 1] + a[-2:]), \
+        tuple(b[0: 2] + b[len(b)//2 : len(b)//2 + 1] + b[-2:])
+
+def y_coordinate_equality(plot_data_func, evalf_func, system):
+    """Checks whether the y-coordinate value of the plotted
+    data point is equal to the value of the function at a
+    particular x."""
+    x, y = plot_data_func(system)
+    x, y = _trim_tuple(x, y)
+    y_exp = tuple(evalf_func(system, x_i) for x_i in x)
+    return all(Abs(y_exp_i - y_i) < 1e-8 for y_exp_i, y_i in zip(y_exp, y))
+
+
+def test_errors():
+    if not matplotlib:
+        skip("Matplotlib not the default backend")
+
+    # Invalid `system` check
+    tfm = TransferFunctionMatrix([[tf6, tf5], [tf5, tf6]])
+    expr = 1/(s**2 - 1)
+    raises(NotImplementedError, lambda: pole_zero_plot(tfm))
+    raises(NotImplementedError, lambda: pole_zero_numerical_data(expr))
+    raises(NotImplementedError, lambda: impulse_response_plot(expr))
+    raises(NotImplementedError, lambda: impulse_response_numerical_data(tfm))
+    raises(NotImplementedError, lambda: step_response_plot(tfm))
+    raises(NotImplementedError, lambda: step_response_numerical_data(expr))
+    raises(NotImplementedError, lambda: ramp_response_plot(expr))
+    raises(NotImplementedError, lambda: ramp_response_numerical_data(tfm))
+    raises(NotImplementedError, lambda: bode_plot(tfm))
+
+    # More than 1 variables
+    tf_a = TransferFunction(a, s + 1, s)
+    raises(ValueError, lambda: pole_zero_plot(tf_a))
+    raises(ValueError, lambda: pole_zero_numerical_data(tf_a))
+    raises(ValueError, lambda: impulse_response_plot(tf_a))
+    raises(ValueError, lambda: impulse_response_numerical_data(tf_a))
+    raises(ValueError, lambda: step_response_plot(tf_a))
+    raises(ValueError, lambda: step_response_numerical_data(tf_a))
+    raises(ValueError, lambda: ramp_response_plot(tf_a))
+    raises(ValueError, lambda: ramp_response_numerical_data(tf_a))
+    raises(ValueError, lambda: bode_plot(tf_a))
+
+    # lower_limit > 0 for response plots
+    raises(ValueError, lambda: impulse_response_plot(tf1, lower_limit=-1))
+    raises(ValueError, lambda: step_response_plot(tf1, lower_limit=-0.1))
+    raises(ValueError, lambda: ramp_response_plot(tf1, lower_limit=-4/3))
+
+    # slope in ramp_response_plot() is negative
+    raises(ValueError, lambda: ramp_response_plot(tf1, slope=-0.1))
+
+    # incorrect frequency or phase unit
+    raises(ValueError, lambda: bode_plot(tf1,freq_unit = 'hz'))
+    raises(ValueError, lambda: bode_plot(tf1,phase_unit = 'degree'))
+
+
+def test_pole_zero():
+    if not numpy:
+        skip("NumPy is required for this test")
+
+    def pz_tester(sys, expected_value):
+        z, p = pole_zero_numerical_data(sys)
+        z_check = numpy.allclose(z, expected_value[0])
+        p_check = numpy.allclose(p, expected_value[1])
+        return p_check and z_check
+
+    exp1 = [[], [-0.24999999999999994+1.3919410907075054j, -0.24999999999999994-1.3919410907075054j]]
+    exp2 = [[0.0], [-0.25+0.3227486121839514j, -0.25-0.3227486121839514j]]
+    exp3 = [[0.0], [-0.5000000000000004+0.8660254037844395j,
+        -0.5000000000000004-0.8660254037844395j, 0.9999999999999998+0j]]
+    exp4 = [[], [5.0, 0.0, 0.0, 0.0]]
+    exp5 = [[-5.645751311064592, -0.5000000000000008, -0.3542486889354093],
+        [-0.24999999999999986+1.3919410907075052j,
+        -0.24999999999999986-1.3919410907075052j, -0.2499999999999998+0.32274861218395134j,
+        -0.2499999999999998-0.32274861218395134j]]
+    exp6 = [[], [-1.1641600331447917-3.545808351896439j,
+          -0.8358399668552097+2.5458083518964383j]]
+
+    assert pz_tester(tf1, exp1)
+    assert pz_tester(tf2, exp2)
+    assert pz_tester(tf3, exp3)
+    assert pz_tester(ser1, exp4)
+    assert pz_tester(par1, exp5)
+    assert pz_tester(tf8, exp6)
+
+
+def test_bode():
+    if not numpy:
+        skip("NumPy is required for this test")
+
+    def bode_phase_evalf(system, point):
+        expr = system.to_expr()
+        _w = Dummy("w", real=True)
+        w_expr = expr.subs({system.var: I*_w})
+        return arg(w_expr).subs({_w: point}).evalf()
+
+    def bode_mag_evalf(system, point):
+        expr = system.to_expr()
+        _w = Dummy("w", real=True)
+        w_expr = expr.subs({system.var: I*_w})
+        return 20*log(Abs(w_expr), 10).subs({_w: point}).evalf()
+
+    def test_bode_data(sys):
+        return y_coordinate_equality(bode_magnitude_numerical_data, bode_mag_evalf, sys) \
+            and y_coordinate_equality(bode_phase_numerical_data, bode_phase_evalf, sys)
+
+    assert test_bode_data(tf1)
+    assert test_bode_data(tf2)
+    assert test_bode_data(tf3)
+    assert test_bode_data(tf4)
+    assert test_bode_data(tf5)
+
+
+def check_point_accuracy(a, b):
+    return all(isclose(*_, rel_tol=1e-1, abs_tol=1e-6
+        ) for _ in zip(a, b))
+
+
+def test_impulse_response():
+    if not numpy:
+        skip("NumPy is required for this test")
+
+    def impulse_res_tester(sys, expected_value):
+        x, y = _to_tuple(*impulse_response_numerical_data(sys,
+            adaptive=False, n=10))
+        x_check = check_point_accuracy(x, expected_value[0])
+        y_check = check_point_accuracy(y, expected_value[1])
+        return x_check and y_check
+
+    exp1 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445,
+        5.555555555555555, 6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0),
+        (0.0, 0.544019738507865, 0.01993849743234938, -0.31140243360893216, -0.022852779906491996, 0.1778306498155759,
+        0.01962941084328499, -0.1013115194573652, -0.014975541213105696, 0.0575789724730714))
+    exp2 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445, 5.555555555555555,
+        6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0), (0.1666666675, 0.08389223412935855,
+        0.02338051973475047, -0.014966807776379383, -0.034645954223054234, -0.040560075735512804,
+        -0.037658628907103885, -0.030149507719590022, -0.021162090730736834, -0.012721292737437523))
+    exp3 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445, 5.555555555555555,
+        6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0), (4.369893391586999e-09, 1.1750333000630964,
+        3.2922404058312473, 9.432290008148343, 28.37098083007151, 86.18577464367974, 261.90356653762115,
+        795.6538758627842, 2416.9920942096983, 7342.159505206647))
+    exp4 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445, 5.555555555555555,
+        6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0), (0.0, 6.17283950617284, 24.69135802469136,
+        55.555555555555564, 98.76543209876544, 154.320987654321, 222.22222222222226, 302.46913580246917,
+        395.0617283950618, 500.0))
+    exp5 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445, 5.555555555555555,
+        6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0), (0.0, -0.10455606138085417,
+        0.06757671513476461, -0.03234567568833768, 0.013582514927757873, -0.005273419510705473,
+        0.0019364083003354075, -0.000680070134067832, 0.00022969845960406913, -7.476094359583917e-05))
+    exp6 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445,
+        5.555555555555555, 6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0),
+        (-6.016699583000218e-09, 0.35039802056107394, 3.3728423827689884, 12.119846079276684,
+        25.86101014293389, 29.352480635282088, -30.49475907497664, -273.8717189554019, -863.2381702029659,
+        -1747.0262164682233))
+    exp7 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335,
+        4.444444444444445, 5.555555555555555, 6.666666666666667, 7.777777777777779,
+        8.88888888888889, 10.0), (0.0, 18.934638095560974, 5346.93244680907, 1384609.8718249386,
+        358161126.65801865, 92645770015.70108, 23964739753087.42, 6198974342083139.0, 1.603492601616059e+18,
+        4.147764422869658e+20))
+
+    assert impulse_res_tester(tf1, exp1)
+    assert impulse_res_tester(tf2, exp2)
+    assert impulse_res_tester(tf3, exp3)
+    assert impulse_res_tester(tf4, exp4)
+    assert impulse_res_tester(tf5, exp5)
+    assert impulse_res_tester(tf7, exp6)
+    assert impulse_res_tester(ser1, exp7)
+
+
+def test_step_response():
+    if not numpy:
+        skip("NumPy is required for this test")
+
+    def step_res_tester(sys, expected_value):
+        x, y = _to_tuple(*step_response_numerical_data(sys,
+            adaptive=False, n=10))
+        x_check = check_point_accuracy(x, expected_value[0])
+        y_check = check_point_accuracy(y, expected_value[1])
+        return x_check and y_check
+
+    exp1 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445,
+        5.555555555555555, 6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0),
+        (-1.9193285738516863e-08, 0.42283495488246126, 0.7840485977945262, 0.5546841805655717,
+        0.33903033806932087, 0.4627251747410237, 0.5909907598988051, 0.5247213989553071,
+        0.4486997874319281, 0.4839358435839171))
+    exp2 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445,
+        5.555555555555555, 6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0),
+        (0.0, 0.13728409095645816, 0.19474559355325086, 0.1974909129243011, 0.16841657696573073,
+        0.12559777736159378, 0.08153828016664713, 0.04360471317348958, 0.015072994568868221,
+        -0.003636420058445484))
+    exp3 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445,
+        5.555555555555555, 6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0),
+        (0.0, 0.6314542141914303, 2.9356520038101035, 9.37731009663807, 28.452300356688376,
+        86.25721933273988, 261.9236645044672, 795.6435410577224, 2416.9786984578764, 7342.154119725917))
+    exp4 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445,
+        5.555555555555555, 6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0),
+        (0.0, 2.286236899862826, 18.28989519890261, 61.72839629629631, 146.31916159122088, 285.7796124828532,
+        493.8271703703705, 784.1792566529494, 1170.553292729767, 1666.6667))
+    exp5 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445,
+        5.555555555555555, 6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0),
+        (-3.999999997894577e-09, 0.6720357068882895, 0.4429938256137113, 0.5182010838004518,
+        0.4944139147159695, 0.5016379853883338, 0.4995466896527733, 0.5001154784851325,
+        0.49997448824584123, 0.5000039745919259))
+    exp6 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445,
+        5.555555555555555, 6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0),
+        (-1.5433688493882158e-09, 0.3428705539937336, 1.1253619102202777, 3.1849962651016517,
+        9.47532757182671, 28.727231099148135, 87.29426924860557, 265.2138681048606, 805.6636260007757,
+        2447.387582370878))
+
+    assert step_res_tester(tf1, exp1)
+    assert step_res_tester(tf2, exp2)
+    assert step_res_tester(tf3, exp3)
+    assert step_res_tester(tf4, exp4)
+    assert step_res_tester(tf5, exp5)
+    assert step_res_tester(ser2, exp6)
+
+
+def test_ramp_response():
+    if not numpy:
+        skip("NumPy is required for this test")
+
+    def ramp_res_tester(sys, num_points, expected_value, slope=1):
+        x, y = _to_tuple(*ramp_response_numerical_data(sys,
+            slope=slope, adaptive=False, n=num_points))
+        x_check = check_point_accuracy(x, expected_value[0])
+        y_check = check_point_accuracy(y, expected_value[1])
+        return x_check and y_check
+
+    exp1 = ((0.0, 2.0, 4.0, 6.0, 8.0, 10.0), (0.0, 0.7324667795033895, 1.9909720978650398,
+        2.7956587704217783, 3.9224897567931514, 4.85022655284895))
+    exp2 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445,
+        5.555555555555555, 6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0),
+        (2.4360213402019326e-08, 0.10175320182493253, 0.33057612497658406, 0.5967937263298935,
+        0.8431511866718248, 1.0398805391471613, 1.1776043125035738, 1.2600994825747305, 1.2981042689274653,
+        1.304684417610106))
+    exp3 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445, 5.555555555555555,
+        6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0), (-3.9329040468771836e-08,
+        0.34686634635794555, 2.9998828170537903, 12.33303690737476, 40.993913948137795, 127.84145222317912,
+        391.41713691996, 1192.0006858708389, 3623.9808672503405, 11011.728034546572))
+    exp4 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445, 5.555555555555555,
+        6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0), (0.0, 1.9051973784484078, 30.483158055174524,
+        154.32098765432104, 487.7305288827924, 1190.7483615302544, 2469.1358024691367, 4574.3789056546275,
+        7803.688462124678, 12500.0))
+    exp5 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445, 5.555555555555555,
+        6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0), (0.0, 3.8844361856975635, 9.141792069209865,
+        14.096349157657231, 19.09783068994694, 24.10179770390321, 29.09907319114121, 34.10040420185154,
+        39.09983919254265, 44.10006013058409))
+    exp6 = ((0.0, 1.1111111111111112, 2.2222222222222223, 3.3333333333333335, 4.444444444444445, 5.555555555555555,
+        6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0), (0.0, 1.1111111111111112, 2.2222222222222223,
+        3.3333333333333335, 4.444444444444445, 5.555555555555555, 6.666666666666667, 7.777777777777779, 8.88888888888889, 10.0))
+
+    assert ramp_res_tester(tf1, 6, exp1)
+    assert ramp_res_tester(tf2, 10, exp2, 1.2)
+    assert ramp_res_tester(tf3, 10, exp3, 1.5)
+    assert ramp_res_tester(tf4, 10, exp4, 3)
+    assert ramp_res_tester(tf5, 10, exp5, 9)
+    assert ramp_res_tester(tf6, 10, exp6)

lib/python3.12/site-packages/sympy/physics/control/tests/test_lti.py

@@ -0,0 +1,1750 @@
+from sympy.core.add import Add
+from sympy.core.function import Function
+from sympy.core.mul import Mul
+from sympy.core.numbers import (I, pi, Rational, oo)
+from sympy.core.power import Pow
+from sympy.core.singleton import S
+from sympy.core.symbol import symbols
+from sympy.functions.elementary.exponential import (exp, log)
+from sympy.functions.elementary.miscellaneous import sqrt
+from sympy.functions.elementary.trigonometric import atan
+from sympy.matrices.dense import eye
+from sympy.polys.polytools import factor
+from sympy.polys.rootoftools import CRootOf
+from sympy.simplify.simplify import simplify
+from sympy.core.containers import Tuple
+from sympy.matrices import ImmutableMatrix, Matrix, ShapeError
+from sympy.physics.control import (TransferFunction, Series, Parallel,
+    Feedback, TransferFunctionMatrix, MIMOSeries, MIMOParallel, MIMOFeedback,
+    StateSpace, gbt, bilinear, forward_diff, backward_diff, phase_margin, gain_margin)
+from sympy.testing.pytest import raises
+
+a, x, b, c, s, g, d, p, k, tau, zeta, wn, T = symbols('a, x, b, c, s, g, d, p, k,\
+    tau, zeta, wn, T')
+a0, a1, a2, a3, b0, b1, b2, b3, c0, c1, c2, c3, d0, d1, d2, d3 = symbols('a0:4,\
+    b0:4, c0:4, d0:4')
+TF1 = TransferFunction(1, s**2 + 2*zeta*wn*s + wn**2, s)
+TF2 = TransferFunction(k, 1, s)
+TF3 = TransferFunction(a2*p - s, a2*s + p, s)
+
+
+def test_TransferFunction_construction():
+    tf = TransferFunction(s + 1, s**2 + s + 1, s)
+    assert tf.num == (s + 1)
+    assert tf.den == (s**2 + s + 1)
+    assert tf.args == (s + 1, s**2 + s + 1, s)
+
+    tf1 = TransferFunction(s + 4, s - 5, s)
+    assert tf1.num == (s + 4)
+    assert tf1.den == (s - 5)
+    assert tf1.args == (s + 4, s - 5, s)
+
+    # using different polynomial variables.
+    tf2 = TransferFunction(p + 3, p**2 - 9, p)
+    assert tf2.num == (p + 3)
+    assert tf2.den == (p**2 - 9)
+    assert tf2.args == (p + 3, p**2 - 9, p)
+
+    tf3 = TransferFunction(p**3 + 5*p**2 + 4, p**4 + 3*p + 1, p)
+    assert tf3.args == (p**3 + 5*p**2 + 4, p**4 + 3*p + 1, p)
+
+    # no pole-zero cancellation on its own.
+    tf4 = TransferFunction((s + 3)*(s - 1), (s - 1)*(s + 5), s)
+    assert tf4.den == (s - 1)*(s + 5)
+    assert tf4.args == ((s + 3)*(s - 1), (s - 1)*(s + 5), s)
+
+    tf4_ = TransferFunction(p + 2, p + 2, p)
+    assert tf4_.args == (p + 2, p + 2, p)
+
+    tf5 = TransferFunction(s - 1, 4 - p, s)
+    assert tf5.args == (s - 1, 4 - p, s)
+
+    tf5_ = TransferFunction(s - 1, s - 1, s)
+    assert tf5_.args == (s - 1, s - 1, s)
+
+    tf6 = TransferFunction(5, 6, s)
+    assert tf6.num == 5
+    assert tf6.den == 6
+    assert tf6.args == (5, 6, s)
+
+    tf6_ = TransferFunction(1/2, 4, s)
+    assert tf6_.num == 0.5
+    assert tf6_.den == 4
+    assert tf6_.args == (0.500000000000000, 4, s)
+
+    tf7 = TransferFunction(3*s**2 + 2*p + 4*s, 8*p**2 + 7*s, s)
+    tf8 = TransferFunction(3*s**2 + 2*p + 4*s, 8*p**2 + 7*s, p)
+    assert not tf7 == tf8
+
+    tf7_ = TransferFunction(a0*s + a1*s**2 + a2*s**3, b0*p - b1*s, s)
+    tf8_ = TransferFunction(a0*s + a1*s**2 + a2*s**3, b0*p - b1*s, s)
+    assert tf7_ == tf8_
+    assert -(-tf7_) == tf7_ == -(-(-(-tf7_)))
+
+    tf9 = TransferFunction(a*s**3 + b*s**2 + g*s + d, d*p + g*p**2 + g*s, s)
+    assert tf9.args == (a*s**3 + b*s**2 + d + g*s, d*p + g*p**2 + g*s, s)
+
+    tf10 = TransferFunction(p**3 + d, g*s**2 + d*s + a, p)
+    tf10_ = TransferFunction(p**3 + d, g*s**2 + d*s + a, p)
+    assert tf10.args == (d + p**3, a + d*s + g*s**2, p)
+    assert tf10_ == tf10
+
+    tf11 = TransferFunction(a1*s + a0, b2*s**2 + b1*s + b0, s)
+    assert tf11.num == (a0 + a1*s)
+    assert tf11.den == (b0 + b1*s + b2*s**2)
+    assert tf11.args == (a0 + a1*s, b0 + b1*s + b2*s**2, s)
+
+    # when just the numerator is 0, leave the denominator alone.
+    tf12 = TransferFunction(0, p**2 - p + 1, p)
+    assert tf12.args == (0, p**2 - p + 1, p)
+
+    tf13 = TransferFunction(0, 1, s)
+    assert tf13.args == (0, 1, s)
+
+    # float exponents
+    tf14 = TransferFunction(a0*s**0.5 + a2*s**0.6 - a1, a1*p**(-8.7), s)
+    assert tf14.args == (a0*s**0.5 - a1 + a2*s**0.6, a1*p**(-8.7), s)
+
+    tf15 = TransferFunction(a2**2*p**(1/4) + a1*s**(-4/5), a0*s - p, p)
+    assert tf15.args == (a1*s**(-0.8) + a2**2*p**0.25, a0*s - p, p)
+
+    omega_o, k_p, k_o, k_i = symbols('omega_o, k_p, k_o, k_i')
+    tf18 = TransferFunction((k_p + k_o*s + k_i/s), s**2 + 2*omega_o*s + omega_o**2, s)
+    assert tf18.num == k_i/s + k_o*s + k_p
+    assert tf18.args == (k_i/s + k_o*s + k_p, omega_o**2 + 2*omega_o*s + s**2, s)
+
+    # ValueError when denominator is zero.
+    raises(ValueError, lambda: TransferFunction(4, 0, s))
+    raises(ValueError, lambda: TransferFunction(s, 0, s))
+    raises(ValueError, lambda: TransferFunction(0, 0, s))
+
+    raises(TypeError, lambda: TransferFunction(Matrix([1, 2, 3]), s, s))
+
+    raises(TypeError, lambda: TransferFunction(s**2 + 2*s - 1, s + 3, 3))
+    raises(TypeError, lambda: TransferFunction(p + 1, 5 - p, 4))
+    raises(TypeError, lambda: TransferFunction(3, 4, 8))
+
+
+def test_TransferFunction_functions():
+    # classmethod from_rational_expression
+    expr_1 = Mul(0, Pow(s, -1, evaluate=False), evaluate=False)
+    expr_2 = s/0
+    expr_3 = (p*s**2 + 5*s)/(s + 1)**3
+    expr_4 = 6
+    expr_5 = ((2 + 3*s)*(5 + 2*s))/((9 + 3*s)*(5 + 2*s**2))
+    expr_6 = (9*s**4 + 4*s**2 + 8)/((s + 1)*(s + 9))
+    tf = TransferFunction(s + 1, s**2 + 2, s)
+    delay = exp(-s/tau)
+    expr_7 = delay*tf.to_expr()
+    H1 = TransferFunction.from_rational_expression(expr_7, s)
+    H2 = TransferFunction(s + 1, (s**2 + 2)*exp(s/tau), s)
+    expr_8 = Add(2,  3*s/(s**2 + 1), evaluate=False)
+
+    assert TransferFunction.from_rational_expression(expr_1) == TransferFunction(0, s, s)
+    raises(ZeroDivisionError, lambda: TransferFunction.from_rational_expression(expr_2))
+    raises(ValueError, lambda: TransferFunction.from_rational_expression(expr_3))
+    assert TransferFunction.from_rational_expression(expr_3, s) == TransferFunction((p*s**2 + 5*s), (s + 1)**3, s)
+    assert TransferFunction.from_rational_expression(expr_3, p) == TransferFunction((p*s**2 + 5*s), (s + 1)**3, p)
+    raises(ValueError, lambda: TransferFunction.from_rational_expression(expr_4))
+    assert TransferFunction.from_rational_expression(expr_4, s) == TransferFunction(6, 1, s)
+    assert TransferFunction.from_rational_expression(expr_5, s) == \
+        TransferFunction((2 + 3*s)*(5 + 2*s), (9 + 3*s)*(5 + 2*s**2), s)
+    assert TransferFunction.from_rational_expression(expr_6, s) == \
+        TransferFunction((9*s**4 + 4*s**2 + 8), (s + 1)*(s + 9), s)
+    assert H1 == H2
+    assert TransferFunction.from_rational_expression(expr_8, s) == \
+        TransferFunction(2*s**2 + 3*s + 2, s**2 + 1, s)
+
+    # classmethod from_coeff_lists
+    tf1 = TransferFunction.from_coeff_lists([1, 2], [3, 4, 5], s)
+    num2 = [p**2, 2*p]
+    den2 = [p**3, p + 1, 4]
+    tf2 = TransferFunction.from_coeff_lists(num2, den2, s)
+    num3 = [1, 2, 3]
+    den3 = [0, 0]
+
+    assert tf1 == TransferFunction(s + 2, 3*s**2 + 4*s + 5, s)
+    assert tf2 == TransferFunction(p**2*s + 2*p, p**3*s**2 + s*(p + 1) + 4, s)
+    raises(ZeroDivisionError, lambda: TransferFunction.from_coeff_lists(num3, den3, s))
+
+    # classmethod from_zpk
+    zeros = [4]
+    poles = [-1+2j, -1-2j]
+    gain = 3
+    tf1 = TransferFunction.from_zpk(zeros, poles, gain, s)
+
+    assert tf1 == TransferFunction(3*s - 12, (s + 1.0 - 2.0*I)*(s + 1.0 + 2.0*I), s)
+
+    # explicitly cancel poles and zeros.
+    tf0 = TransferFunction(s**5 + s**3 + s, s - s**2, s)
+    a = TransferFunction(-(s**4 + s**2 + 1), s - 1, s)
+    assert tf0.simplify() == simplify(tf0) == a
+
+    tf1 = TransferFunction((p + 3)*(p - 1), (p - 1)*(p + 5), p)
+    b = TransferFunction(p + 3, p + 5, p)
+    assert tf1.simplify() == simplify(tf1) == b
+
+    # expand the numerator and the denominator.
+    G1 = TransferFunction((1 - s)**2, (s**2 + 1)**2, s)
+    G2 = TransferFunction(1, -3, p)
+    c = (a2*s**p + a1*s**s + a0*p**p)*(p**s + s**p)
+    d = (b0*s**s + b1*p**s)*(b2*s*p + p**p)
+    e = a0*p**p*p**s + a0*p**p*s**p + a1*p**s*s**s + a1*s**p*s**s + a2*p**s*s**p + a2*s**(2*p)
+    f = b0*b2*p*s*s**s + b0*p**p*s**s + b1*b2*p*p**s*s + b1*p**p*p**s
+    g = a1*a2*s*s**p + a1*p*s + a2*b1*p*s*s**p + b1*p**2*s
+    G3 = TransferFunction(c, d, s)
+    G4 = TransferFunction(a0*s**s - b0*p**p, (a1*s + b1*s*p)*(a2*s**p + p), p)
+
+    assert G1.expand() == TransferFunction(s**2 - 2*s + 1, s**4 + 2*s**2 + 1, s)
+    assert tf1.expand() == TransferFunction(p**2 + 2*p - 3, p**2 + 4*p - 5, p)
+    assert G2.expand() == G2
+    assert G3.expand() == TransferFunction(e, f, s)
+    assert G4.expand() == TransferFunction(a0*s**s - b0*p**p, g, p)
+
+    # purely symbolic polynomials.
+    p1 = a1*s + a0
+    p2 = b2*s**2 + b1*s + b0
+    SP1 = TransferFunction(p1, p2, s)
+    expect1 = TransferFunction(2.0*s + 1.0, 5.0*s**2 + 4.0*s + 3.0, s)
+    expect1_ = TransferFunction(2*s + 1, 5*s**2 + 4*s + 3, s)
+    assert SP1.subs({a0: 1, a1: 2, b0: 3, b1: 4, b2: 5}) == expect1_
+    assert SP1.subs({a0: 1, a1: 2, b0: 3, b1: 4, b2: 5}).evalf() == expect1
+    assert expect1_.evalf() == expect1
+
+    c1, d0, d1, d2 = symbols('c1, d0:3')
+    p3, p4 = c1*p, d2*p**3 + d1*p**2 - d0
+    SP2 = TransferFunction(p3, p4, p)
+    expect2 = TransferFunction(2.0*p, 5.0*p**3 + 2.0*p**2 - 3.0, p)
+    expect2_ = TransferFunction(2*p, 5*p**3 + 2*p**2 - 3, p)
+    assert SP2.subs({c1: 2, d0: 3, d1: 2, d2: 5}) == expect2_
+    assert SP2.subs({c1: 2, d0: 3, d1: 2, d2: 5}).evalf() == expect2
+    assert expect2_.evalf() == expect2
+
+    SP3 = TransferFunction(a0*p**3 + a1*s**2 - b0*s + b1, a1*s + p, s)
+    expect3 = TransferFunction(2.0*p**3 + 4.0*s**2 - s + 5.0, p + 4.0*s, s)
+    expect3_ = TransferFunction(2*p**3 + 4*s**2 - s + 5, p + 4*s, s)
+    assert SP3.subs({a0: 2, a1: 4, b0: 1, b1: 5}) == expect3_
+    assert SP3.subs({a0: 2, a1: 4, b0: 1, b1: 5}).evalf() == expect3
+    assert expect3_.evalf() == expect3
+
+    SP4 = TransferFunction(s - a1*p**3, a0*s + p, p)
+    expect4 = TransferFunction(7.0*p**3 + s, p - s, p)
+    expect4_ = TransferFunction(7*p**3 + s, p - s, p)
+    assert SP4.subs({a0: -1, a1: -7}) == expect4_
+    assert SP4.subs({a0: -1, a1: -7}).evalf() == expect4
+    assert expect4_.evalf() == expect4
+
+    # evaluate the transfer function at particular frequencies.
+    assert tf1.eval_frequency(wn) == wn**2/(wn**2 + 4*wn - 5) + 2*wn/(wn**2 + 4*wn - 5) - 3/(wn**2 + 4*wn - 5)
+    assert G1.eval_frequency(1 + I) == S(3)/25 + S(4)*I/25
+    assert G4.eval_frequency(S(5)/3) == \
+        a0*s**s/(a1*a2*s**(S(8)/3) + S(5)*a1*s/3 + 5*a2*b1*s**(S(8)/3)/3 + S(25)*b1*s/9) - 5*3**(S(1)/3)*5**(S(2)/3)*b0/(9*a1*a2*s**(S(8)/3) + 15*a1*s + 15*a2*b1*s**(S(8)/3) + 25*b1*s)
+
+    # Low-frequency (or DC) gain.
+    assert tf0.dc_gain() == 1
+    assert tf1.dc_gain() == Rational(3, 5)
+    assert SP2.dc_gain() == 0
+    assert expect4.dc_gain() == -1
+    assert expect2_.dc_gain() == 0
+    assert TransferFunction(1, s, s).dc_gain() == oo
+
+    # Poles of a transfer function.
+    tf_ = TransferFunction(x**3 - k, k, x)
+    _tf = TransferFunction(k, x**4 - k, x)
+    TF_ = TransferFunction(x**2, x**10 + x + x**2, x)
+    _TF = TransferFunction(x**10 + x + x**2, x**2, x)
+    assert G1.poles() == [I, I, -I, -I]
+    assert G2.poles() == []
+    assert tf1.poles() == [-5, 1]
+    assert expect4_.poles() == [s]
+    assert SP4.poles() == [-a0*s]
+    assert expect3.poles() == [-0.25*p]
+    assert str(expect2.poles()) == str([0.729001428685125, -0.564500714342563 - 0.710198984796332*I, -0.564500714342563 + 0.710198984796332*I])
+    assert str(expect1.poles()) == str([-0.4 - 0.66332495807108*I, -0.4 + 0.66332495807108*I])
+    assert _tf.poles() == [k**(Rational(1, 4)), -k**(Rational(1, 4)), I*k**(Rational(1, 4)), -I*k**(Rational(1, 4))]
+    assert TF_.poles() == [CRootOf(x**9 + x + 1, 0), 0, CRootOf(x**9 + x + 1, 1), CRootOf(x**9 + x + 1, 2),
+        CRootOf(x**9 + x + 1, 3), CRootOf(x**9 + x + 1, 4), CRootOf(x**9 + x + 1, 5), CRootOf(x**9 + x + 1, 6),
+        CRootOf(x**9 + x + 1, 7), CRootOf(x**9 + x + 1, 8)]
+    raises(NotImplementedError, lambda: TransferFunction(x**2, a0*x**10 + x + x**2, x).poles())
+
+    # Stability of a transfer function.
+    q, r = symbols('q, r', negative=True)
+    t = symbols('t', positive=True)
+    TF_ = TransferFunction(s**2 + a0 - a1*p, q*s - r, s)
+    stable_tf = TransferFunction(s**2 + a0 - a1*p, q*s - 1, s)
+    stable_tf_ = TransferFunction(s**2 + a0 - a1*p, q*s - t, s)
+
+    assert G1.is_stable() is False
+    assert G2.is_stable() is True
+    assert tf1.is_stable() is False   # as one pole is +ve, and the other is -ve.
+    assert expect2.is_stable() is False
+    assert expect1.is_stable() is True
+    assert stable_tf.is_stable() is True
+    assert stable_tf_.is_stable() is True
+    assert TF_.is_stable() is False
+    assert expect4_.is_stable() is None   # no assumption provided for the only pole 's'.
+    assert SP4.is_stable() is None
+
+    # Zeros of a transfer function.
+    assert G1.zeros() == [1, 1]
+    assert G2.zeros() == []
+    assert tf1.zeros() == [-3, 1]
+    assert expect4_.zeros() == [7**(Rational(2, 3))*(-s)**(Rational(1, 3))/7, -7**(Rational(2, 3))*(-s)**(Rational(1, 3))/14 -
+        sqrt(3)*7**(Rational(2, 3))*I*(-s)**(Rational(1, 3))/14, -7**(Rational(2, 3))*(-s)**(Rational(1, 3))/14 + sqrt(3)*7**(Rational(2, 3))*I*(-s)**(Rational(1, 3))/14]
+    assert SP4.zeros() == [(s/a1)**(Rational(1, 3)), -(s/a1)**(Rational(1, 3))/2 - sqrt(3)*I*(s/a1)**(Rational(1, 3))/2,
+        -(s/a1)**(Rational(1, 3))/2 + sqrt(3)*I*(s/a1)**(Rational(1, 3))/2]
+    assert str(expect3.zeros()) == str([0.125 - 1.11102430216445*sqrt(-0.405063291139241*p**3 - 1.0),
+        1.11102430216445*sqrt(-0.405063291139241*p**3 - 1.0) + 0.125])
+    assert tf_.zeros() == [k**(Rational(1, 3)), -k**(Rational(1, 3))/2 - sqrt(3)*I*k**(Rational(1, 3))/2,
+        -k**(Rational(1, 3))/2 + sqrt(3)*I*k**(Rational(1, 3))/2]
+    assert _TF.zeros() == [CRootOf(x**9 + x + 1, 0), 0, CRootOf(x**9 + x + 1, 1), CRootOf(x**9 + x + 1, 2),
+        CRootOf(x**9 + x + 1, 3), CRootOf(x**9 + x + 1, 4), CRootOf(x**9 + x + 1, 5), CRootOf(x**9 + x + 1, 6),
+        CRootOf(x**9 + x + 1, 7), CRootOf(x**9 + x + 1, 8)]
+    raises(NotImplementedError, lambda: TransferFunction(a0*x**10 + x + x**2, x**2, x).zeros())
+
+    # negation of TF.
+    tf2 = TransferFunction(s + 3, s**2 - s**3 + 9, s)
+    tf3 = TransferFunction(-3*p + 3, 1 - p, p)
+    assert -tf2 == TransferFunction(-s - 3, s**2 - s**3 + 9, s)
+    assert -tf3 == TransferFunction(3*p - 3, 1 - p, p)
+
+    # taking power of a TF.
+    tf4 = TransferFunction(p + 4, p - 3, p)
+    tf5 = TransferFunction(s**2 + 1, 1 - s, s)
+    expect2 = TransferFunction((s**2 + 1)**3, (1 - s)**3, s)
+    expect1 = TransferFunction((p + 4)**2, (p - 3)**2, p)
+    assert (tf4*tf4).doit() == tf4**2 == pow(tf4, 2) == expect1
+    assert (tf5*tf5*tf5).doit() == tf5**3 == pow(tf5, 3) == expect2
+    assert tf5**0 == pow(tf5, 0) == TransferFunction(1, 1, s)
+    assert Series(tf4).doit()**-1 == tf4**-1 == pow(tf4, -1) == TransferFunction(p - 3, p + 4, p)
+    assert (tf5*tf5).doit()**-1 == tf5**-2 == pow(tf5, -2) == TransferFunction((1 - s)**2, (s**2 + 1)**2, s)
+
+    raises(ValueError, lambda: tf4**(s**2 + s - 1))
+    raises(ValueError, lambda: tf5**s)
+    raises(ValueError, lambda: tf4**tf5)
+
+    # SymPy's own functions.
+    tf = TransferFunction(s - 1, s**2 - 2*s + 1, s)
+    tf6 = TransferFunction(s + p, p**2 - 5, s)
+    assert factor(tf) == TransferFunction(s - 1, (s - 1)**2, s)
+    assert tf.num.subs(s, 2) == tf.den.subs(s, 2) == 1
+    # subs & xreplace
+    assert tf.subs(s, 2) == TransferFunction(s - 1, s**2 - 2*s + 1, s)
+    assert tf6.subs(p, 3) == TransferFunction(s + 3, 4, s)
+    assert tf3.xreplace({p: s}) == TransferFunction(-3*s + 3, 1 - s, s)
+    raises(TypeError, lambda: tf3.xreplace({p: exp(2)}))
+    assert tf3.subs(p, exp(2)) == tf3
+
+    tf7 = TransferFunction(a0*s**p + a1*p**s, a2*p - s, s)
+    assert tf7.xreplace({s: k}) == TransferFunction(a0*k**p + a1*p**k, a2*p - k, k)
+    assert tf7.subs(s, k) == TransferFunction(a0*s**p + a1*p**s, a2*p - s, s)
+
+    # Conversion to Expr with to_expr()
+    tf8 = TransferFunction(a0*s**5 + 5*s**2 + 3, s**6 - 3, s)
+    tf9 = TransferFunction((5 + s), (5 + s)*(6 + s), s)
+    tf10 = TransferFunction(0, 1, s)
+    tf11 = TransferFunction(1, 1, s)
+    assert tf8.to_expr() == Mul((a0*s**5 + 5*s**2 + 3), Pow((s**6 - 3), -1, evaluate=False), evaluate=False)
+    assert tf9.to_expr() == Mul((s + 5), Pow((5 + s)*(6 + s), -1, evaluate=False), evaluate=False)
+    assert tf10.to_expr() == Mul(S(0), Pow(1, -1, evaluate=False), evaluate=False)
+    assert tf11.to_expr() == Pow(1, -1, evaluate=False)
+
+def test_TransferFunction_addition_and_subtraction():
+    tf1 = TransferFunction(s + 6, s - 5, s)
+    tf2 = TransferFunction(s + 3, s + 1, s)
+    tf3 = TransferFunction(s + 1, s**2 + s + 1, s)
+    tf4 = TransferFunction(p, 2 - p, p)
+
+    # addition
+    assert tf1 + tf2 == Parallel(tf1, tf2)
+    assert tf3 + tf1 == Parallel(tf3, tf1)
+    assert -tf1 + tf2 + tf3 == Parallel(-tf1, tf2, tf3)
+    assert tf1 + (tf2 + tf3) == Parallel(tf1, tf2, tf3)
+
+    c = symbols("c", commutative=False)
+    raises(ValueError, lambda: tf1 + Matrix([1, 2, 3]))
+    raises(ValueError, lambda: tf2 + c)
+    raises(ValueError, lambda: tf3 + tf4)
+    raises(ValueError, lambda: tf1 + (s - 1))
+    raises(ValueError, lambda: tf1 + 8)
+    raises(ValueError, lambda: (1 - p**3) + tf1)
+
+    # subtraction
+    assert tf1 - tf2 == Parallel(tf1, -tf2)
+    assert tf3 - tf2 == Parallel(tf3, -tf2)
+    assert -tf1 - tf3 == Parallel(-tf1, -tf3)
+    assert tf1 - tf2 + tf3 == Parallel(tf1, -tf2, tf3)
+
+    raises(ValueError, lambda: tf1 - Matrix([1, 2, 3]))
+    raises(ValueError, lambda: tf3 - tf4)
+    raises(ValueError, lambda: tf1 - (s - 1))
+    raises(ValueError, lambda: tf1 - 8)
+    raises(ValueError, lambda: (s + 5) - tf2)
+    raises(ValueError, lambda: (1 + p**4) - tf1)
+
+
+def test_TransferFunction_multiplication_and_division():
+    G1 = TransferFunction(s + 3, -s**3 + 9, s)
+    G2 = TransferFunction(s + 1, s - 5, s)
+    G3 = TransferFunction(p, p**4 - 6, p)
+    G4 = TransferFunction(p + 4, p - 5, p)
+    G5 = TransferFunction(s + 6, s - 5, s)
+    G6 = TransferFunction(s + 3, s + 1, s)
+    G7 = TransferFunction(1, 1, s)
+
+    # multiplication
+    assert G1*G2 == Series(G1, G2)
+    assert -G1*G5 == Series(-G1, G5)
+    assert -G2*G5*-G6 == Series(-G2, G5, -G6)
+    assert -G1*-G2*-G5*-G6 == Series(-G1, -G2, -G5, -G6)
+    assert G3*G4 == Series(G3, G4)
+    assert (G1*G2)*-(G5*G6) == \
+        Series(G1, G2, TransferFunction(-1, 1, s), Series(G5, G6))
+    assert G1*G2*(G5 + G6) == Series(G1, G2, Parallel(G5, G6))
+
+    # division - See ``test_Feedback_functions()`` for division by Parallel objects.
+    assert G5/G6 == Series(G5, pow(G6, -1))
+    assert -G3/G4 == Series(-G3, pow(G4, -1))
+    assert (G5*G6)/G7 == Series(G5, G6, pow(G7, -1))
+
+    c = symbols("c", commutative=False)
+    raises(ValueError, lambda: G3 * Matrix([1, 2, 3]))
+    raises(ValueError, lambda: G1 * c)
+    raises(ValueError, lambda: G3 * G5)
+    raises(ValueError, lambda: G5 * (s - 1))
+    raises(ValueError, lambda: 9 * G5)
+
+    raises(ValueError, lambda: G3 / Matrix([1, 2, 3]))
+    raises(ValueError, lambda: G6 / 0)
+    raises(ValueError, lambda: G3 / G5)
+    raises(ValueError, lambda: G5 / 2)
+    raises(ValueError, lambda: G5 / s**2)
+    raises(ValueError, lambda: (s - 4*s**2) / G2)
+    raises(ValueError, lambda: 0 / G4)
+    raises(ValueError, lambda: G7 / (1 + G6))
+    raises(ValueError, lambda: G7 / (G5 * G6))
+    raises(ValueError, lambda: G7 / (G7 + (G5 + G6)))
+
+
+def test_TransferFunction_is_proper():
+    omega_o, zeta, tau = symbols('omega_o, zeta, tau')
+    G1 = TransferFunction(omega_o**2, s**2 + p*omega_o*zeta*s + omega_o**2, omega_o)
+    G2 = TransferFunction(tau - s**3, tau + p**4, tau)
+    G3 = TransferFunction(a*b*s**3 + s**2 - a*p + s, b - s*p**2, p)
+    G4 = TransferFunction(b*s**2 + p**2 - a*p + s, b - p**2, s)
+    assert G1.is_proper
+    assert G2.is_proper
+    assert G3.is_proper
+    assert not G4.is_proper
+
+
+def test_TransferFunction_is_strictly_proper():
+    omega_o, zeta, tau = symbols('omega_o, zeta, tau')
+    tf1 = TransferFunction(omega_o**2, s**2 + p*omega_o*zeta*s + omega_o**2, omega_o)
+    tf2 = TransferFunction(tau - s**3, tau + p**4, tau)
+    tf3 = TransferFunction(a*b*s**3 + s**2 - a*p + s, b - s*p**2, p)
+    tf4 = TransferFunction(b*s**2 + p**2 - a*p + s, b - p**2, s)
+    assert not tf1.is_strictly_proper
+    assert not tf2.is_strictly_proper
+    assert tf3.is_strictly_proper
+    assert not tf4.is_strictly_proper
+
+
+def test_TransferFunction_is_biproper():
+    tau, omega_o, zeta = symbols('tau, omega_o, zeta')
+    tf1 = TransferFunction(omega_o**2, s**2 + p*omega_o*zeta*s + omega_o**2, omega_o)
+    tf2 = TransferFunction(tau - s**3, tau + p**4, tau)
+    tf3 = TransferFunction(a*b*s**3 + s**2 - a*p + s, b - s*p**2, p)
+    tf4 = TransferFunction(b*s**2 + p**2 - a*p + s, b - p**2, s)
+    assert tf1.is_biproper
+    assert tf2.is_biproper
+    assert not tf3.is_biproper
+    assert not tf4.is_biproper
+
+
+def test_Series_construction():
+    tf = TransferFunction(a0*s**3 + a1*s**2 - a2*s, b0*p**4 + b1*p**3 - b2*s*p, s)
+    tf2 = TransferFunction(a2*p - s, a2*s + p, s)
+    tf3 = TransferFunction(a0*p + p**a1 - s, p, p)
+    tf4 = TransferFunction(1, s**2 + 2*zeta*wn*s + wn**2, s)
+    inp = Function('X_d')(s)
+    out = Function('X')(s)
+
+    s0 = Series(tf, tf2)
+    assert s0.args == (tf, tf2)
+    assert s0.var == s
+
+    s1 = Series(Parallel(tf, -tf2), tf2)
+    assert s1.args == (Parallel(tf, -tf2), tf2)
+    assert s1.var == s
+
+    tf3_ = TransferFunction(inp, 1, s)
+    tf4_ = TransferFunction(-out, 1, s)
+    s2 = Series(tf, Parallel(tf3_, tf4_), tf2)
+    assert s2.args == (tf, Parallel(tf3_, tf4_), tf2)
+
+    s3 = Series(tf, tf2, tf4)
+    assert s3.args == (tf, tf2, tf4)
+
+    s4 = Series(tf3_, tf4_)
+    assert s4.args == (tf3_, tf4_)
+    assert s4.var == s
+
+    s6 = Series(tf2, tf4, Parallel(tf2, -tf), tf4)
+    assert s6.args == (tf2, tf4, Parallel(tf2, -tf), tf4)
+
+    s7 = Series(tf, tf2)
+    assert s0 == s7
+    assert not s0 == s2
+
+    raises(ValueError, lambda: Series(tf, tf3))
+    raises(ValueError, lambda: Series(tf, tf2, tf3, tf4))
+    raises(ValueError, lambda: Series(-tf3, tf2))
+    raises(TypeError, lambda: Series(2, tf, tf4))
+    raises(TypeError, lambda: Series(s**2 + p*s, tf3, tf2))
+    raises(TypeError, lambda: Series(tf3, Matrix([1, 2, 3, 4])))
+
+
+def test_MIMOSeries_construction():
+    tf_1 = TransferFunction(a0*s**3 + a1*s**2 - a2*s, b0*p**4 + b1*p**3 - b2*s*p, s)
+    tf_2 = TransferFunction(a2*p - s, a2*s + p, s)
+    tf_3 = TransferFunction(1, s**2 + 2*zeta*wn*s + wn**2, s)
+
+    tfm_1 = TransferFunctionMatrix([[tf_1, tf_2, tf_3], [-tf_3, -tf_2, tf_1]])
+    tfm_2 = TransferFunctionMatrix([[-tf_2], [-tf_2], [-tf_3]])
+    tfm_3 = TransferFunctionMatrix([[-tf_3]])
+    tfm_4 = TransferFunctionMatrix([[TF3], [TF2], [-TF1]])
+    tfm_5 = TransferFunctionMatrix.from_Matrix(Matrix([1/p]), p)
+
+    s8 = MIMOSeries(tfm_2, tfm_1)
+    assert s8.args == (tfm_2, tfm_1)
+    assert s8.var == s
+    assert s8.shape == (s8.num_outputs, s8.num_inputs) == (2, 1)
+
+    s9 = MIMOSeries(tfm_3, tfm_2, tfm_1)
+    assert s9.args == (tfm_3, tfm_2, tfm_1)
+    assert s9.var == s
+    assert s9.shape == (s9.num_outputs, s9.num_inputs) == (2, 1)
+
+    s11 = MIMOSeries(tfm_3, MIMOParallel(-tfm_2, -tfm_4), tfm_1)
+    assert s11.args == (tfm_3, MIMOParallel(-tfm_2, -tfm_4), tfm_1)
+    assert s11.shape == (s11.num_outputs, s11.num_inputs) == (2, 1)
+
+    # arg cannot be empty tuple.
+    raises(ValueError, lambda: MIMOSeries())
+
+    # arg cannot contain SISO as well as MIMO systems.
+    raises(TypeError, lambda: MIMOSeries(tfm_1, tf_1))
+
+    # for all the adjacent transfer function matrices:
+    # no. of inputs of first TFM must be equal to the no. of outputs of the second TFM.
+    raises(ValueError, lambda: MIMOSeries(tfm_1, tfm_2, -tfm_1))
+
+    # all the TFMs must use the same complex variable.
+    raises(ValueError, lambda: MIMOSeries(tfm_3, tfm_5))
+
+    # Number or expression not allowed in the arguments.
+    raises(TypeError, lambda: MIMOSeries(2, tfm_2, tfm_3))
+    raises(TypeError, lambda: MIMOSeries(s**2 + p*s, -tfm_2, tfm_3))
+    raises(TypeError, lambda: MIMOSeries(Matrix([1/p]), tfm_3))
+
+
+def test_Series_functions():
+    tf1 = TransferFunction(1, s**2 + 2*zeta*wn*s + wn**2, s)
+    tf2 = TransferFunction(k, 1, s)
+    tf3 = TransferFunction(a2*p - s, a2*s + p, s)
+    tf4 = TransferFunction(a0*p + p**a1 - s, p, p)
+    tf5 = TransferFunction(a1*s**2 + a2*s - a0, s + a0, s)
+
+    assert tf1*tf2*tf3 == Series(tf1, tf2, tf3) == Series(Series(tf1, tf2), tf3) \
+        == Series(tf1, Series(tf2, tf3))
+    assert tf1*(tf2 + tf3) == Series(tf1, Parallel(tf2, tf3))
+    assert tf1*tf2 + tf5 == Parallel(Series(tf1, tf2), tf5)
+    assert tf1*tf2 - tf5 == Parallel(Series(tf1, tf2), -tf5)
+    assert tf1*tf2 + tf3 + tf5 == Parallel(Series(tf1, tf2), tf3, tf5)
+    assert tf1*tf2 - tf3 - tf5 == Parallel(Series(tf1, tf2), -tf3, -tf5)
+    assert tf1*tf2 - tf3 + tf5 == Parallel(Series(tf1, tf2), -tf3, tf5)
+    assert tf1*tf2 + tf3*tf5 == Parallel(Series(tf1, tf2), Series(tf3, tf5))
+    assert tf1*tf2 - tf3*tf5 == Parallel(Series(tf1, tf2), Series(TransferFunction(-1, 1, s), Series(tf3, tf5)))
+    assert tf2*tf3*(tf2 - tf1)*tf3 == Series(tf2, tf3, Parallel(tf2, -tf1), tf3)
+    assert -tf1*tf2 == Series(-tf1, tf2)
+    assert -(tf1*tf2) == Series(TransferFunction(-1, 1, s), Series(tf1, tf2))
+    raises(ValueError, lambda: tf1*tf2*tf4)
+    raises(ValueError, lambda: tf1*(tf2 - tf4))
+    raises(ValueError, lambda: tf3*Matrix([1, 2, 3]))
+
+    # evaluate=True -> doit()
+    assert Series(tf1, tf2, evaluate=True) == Series(tf1, tf2).doit() == \
+        TransferFunction(k, s**2 + 2*s*wn*zeta + wn**2, s)
+    assert Series(tf1, tf2, Parallel(tf1, -tf3), evaluate=True) == Series(tf1, tf2, Parallel(tf1, -tf3)).doit() == \
+        TransferFunction(k*(a2*s + p + (-a2*p + s)*(s**2 + 2*s*wn*zeta + wn**2)), (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2)**2, s)
+    assert Series(tf2, tf1, -tf3, evaluate=True) == Series(tf2, tf1, -tf3).doit() == \
+        TransferFunction(k*(-a2*p + s), (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), s)
+    assert not Series(tf1, -tf2, evaluate=False) == Series(tf1, -tf2).doit()
+
+    assert Series(Parallel(tf1, tf2), Parallel(tf2, -tf3)).doit() == \
+        TransferFunction((k*(s**2 + 2*s*wn*zeta + wn**2) + 1)*(-a2*p + k*(a2*s + p) + s), (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), s)
+    assert Series(-tf1, -tf2, -tf3).doit() == \
+        TransferFunction(k*(-a2*p + s), (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), s)
+    assert -Series(tf1, tf2, tf3).doit() == \
+        TransferFunction(-k*(a2*p - s), (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), s)
+    assert Series(tf2, tf3, Parallel(tf2, -tf1), tf3).doit() == \
+        TransferFunction(k*(a2*p - s)**2*(k*(s**2 + 2*s*wn*zeta + wn**2) - 1), (a2*s + p)**2*(s**2 + 2*s*wn*zeta + wn**2), s)
+
+    assert Series(tf1, tf2).rewrite(TransferFunction) == TransferFunction(k, s**2 + 2*s*wn*zeta + wn**2, s)
+    assert Series(tf2, tf1, -tf3).rewrite(TransferFunction) == \
+        TransferFunction(k*(-a2*p + s), (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), s)
+
+    S1 = Series(Parallel(tf1, tf2), Parallel(tf2, -tf3))
+    assert S1.is_proper
+    assert not S1.is_strictly_proper
+    assert S1.is_biproper
+
+    S2 = Series(tf1, tf2, tf3)
+    assert S2.is_proper
+    assert S2.is_strictly_proper
+    assert not S2.is_biproper
+
+    S3 = Series(tf1, -tf2, Parallel(tf1, -tf3))
+    assert S3.is_proper
+    assert S3.is_strictly_proper
+    assert not S3.is_biproper
+
+
+def test_MIMOSeries_functions():
+    tfm1 = TransferFunctionMatrix([[TF1, TF2, TF3], [-TF3, -TF2, TF1]])
+    tfm2 = TransferFunctionMatrix([[-TF1], [-TF2], [-TF3]])
+    tfm3 = TransferFunctionMatrix([[-TF1]])
+    tfm4 = TransferFunctionMatrix([[-TF2, -TF3], [-TF1, TF2]])
+    tfm5 = TransferFunctionMatrix([[TF2, -TF2], [-TF3, -TF2]])
+    tfm6 = TransferFunctionMatrix([[-TF3], [TF1]])
+    tfm7 = TransferFunctionMatrix([[TF1], [-TF2]])
+
+    assert tfm1*tfm2 + tfm6 == MIMOParallel(MIMOSeries(tfm2, tfm1), tfm6)
+    assert tfm1*tfm2 + tfm7 + tfm6 == MIMOParallel(MIMOSeries(tfm2, tfm1), tfm7, tfm6)
+    assert tfm1*tfm2 - tfm6 - tfm7 == MIMOParallel(MIMOSeries(tfm2, tfm1), -tfm6, -tfm7)
+    assert tfm4*tfm5 + (tfm4 - tfm5) == MIMOParallel(MIMOSeries(tfm5, tfm4), tfm4, -tfm5)
+    assert tfm4*-tfm6 + (-tfm4*tfm6) == MIMOParallel(MIMOSeries(-tfm6, tfm4), MIMOSeries(tfm6, -tfm4))
+
+    raises(ValueError, lambda: tfm1*tfm2 + TF1)
+    raises(TypeError, lambda: tfm1*tfm2 + a0)
+    raises(TypeError, lambda: tfm4*tfm6 - (s - 1))
+    raises(TypeError, lambda: tfm4*-tfm6 - 8)
+    raises(TypeError, lambda: (-1 + p**5) + tfm1*tfm2)
+
+    # Shape criteria.
+
+    raises(TypeError, lambda: -tfm1*tfm2 + tfm4)
+    raises(TypeError, lambda: tfm1*tfm2 - tfm4 + tfm5)
+    raises(TypeError, lambda: tfm1*tfm2 - tfm4*tfm5)
+
+    assert tfm1*tfm2*-tfm3 == MIMOSeries(-tfm3, tfm2, tfm1)
+    assert (tfm1*-tfm2)*tfm3 == MIMOSeries(tfm3, -tfm2, tfm1)
+
+    # Multiplication of a Series object with a SISO TF not allowed.
+
+    raises(ValueError, lambda: tfm4*tfm5*TF1)
+    raises(TypeError, lambda: tfm4*tfm5*a1)
+    raises(TypeError, lambda: tfm4*-tfm5*(s - 2))
+    raises(TypeError, lambda: tfm5*tfm4*9)
+    raises(TypeError, lambda: (-p**3 + 1)*tfm5*tfm4)
+
+    # Transfer function matrix in the arguments.
+    assert (MIMOSeries(tfm2, tfm1, evaluate=True) == MIMOSeries(tfm2, tfm1).doit()
+        == TransferFunctionMatrix(((TransferFunction(-k**2*(a2*s + p)**2*(s**2 + 2*s*wn*zeta + wn**2)**2 + (-a2*p + s)*(a2*p - s)*(s**2 + 2*s*wn*zeta + wn**2)**2 - (a2*s + p)**2,
+        (a2*s + p)**2*(s**2 + 2*s*wn*zeta + wn**2)**2, s),),
+        (TransferFunction(k**2*(a2*s + p)**2*(s**2 + 2*s*wn*zeta + wn**2)**2 + (-a2*p + s)*(a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2) + (a2*p - s)*(a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2),
+        (a2*s + p)**2*(s**2 + 2*s*wn*zeta + wn**2)**2, s),))))
+
+    # doit() should not cancel poles and zeros.
+    mat_1 = Matrix([[1/(1+s), (1+s)/(1+s**2+2*s)**3]])
+    mat_2 = Matrix([[(1+s)], [(1+s**2+2*s)**3/(1+s)]])
+    tm_1, tm_2 = TransferFunctionMatrix.from_Matrix(mat_1, s), TransferFunctionMatrix.from_Matrix(mat_2, s)
+    assert (MIMOSeries(tm_2, tm_1).doit()
+        == TransferFunctionMatrix(((TransferFunction(2*(s + 1)**2*(s**2 + 2*s + 1)**3, (s + 1)**2*(s**2 + 2*s + 1)**3, s),),)))
+    assert MIMOSeries(tm_2, tm_1).doit().simplify() == TransferFunctionMatrix(((TransferFunction(2, 1, s),),))
+
+    # calling doit() will expand the internal Series and Parallel objects.
+    assert (MIMOSeries(-tfm3, -tfm2, tfm1, evaluate=True)
+        == MIMOSeries(-tfm3, -tfm2, tfm1).doit()
+        == TransferFunctionMatrix(((TransferFunction(k**2*(a2*s + p)**2*(s**2 + 2*s*wn*zeta + wn**2)**2 + (a2*p - s)**2*(s**2 + 2*s*wn*zeta + wn**2)**2 + (a2*s + p)**2,
+        (a2*s + p)**2*(s**2 + 2*s*wn*zeta + wn**2)**3, s),),
+        (TransferFunction(-k**2*(a2*s + p)**2*(s**2 + 2*s*wn*zeta + wn**2)**2 + (-a2*p + s)*(a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2) + (a2*p - s)*(a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2),
+        (a2*s + p)**2*(s**2 + 2*s*wn*zeta + wn**2)**3, s),))))
+    assert (MIMOSeries(MIMOParallel(tfm4, tfm5), tfm5, evaluate=True)
+        == MIMOSeries(MIMOParallel(tfm4, tfm5), tfm5).doit()
+        == TransferFunctionMatrix(((TransferFunction(-k*(-a2*s - p + (-a2*p + s)*(s**2 + 2*s*wn*zeta + wn**2)), (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), s), TransferFunction(k*(-a2*p - \
+            k*(a2*s + p) + s), a2*s + p, s)), (TransferFunction(-k*(-a2*s - p + (-a2*p + s)*(s**2 + 2*s*wn*zeta + wn**2)), (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), s), \
+            TransferFunction((-a2*p + s)*(-a2*p - k*(a2*s + p) + s), (a2*s + p)**2, s)))) == MIMOSeries(MIMOParallel(tfm4, tfm5), tfm5).rewrite(TransferFunctionMatrix))
+
+
+def test_Parallel_construction():
+    tf = TransferFunction(a0*s**3 + a1*s**2 - a2*s, b0*p**4 + b1*p**3 - b2*s*p, s)
+    tf2 = TransferFunction(a2*p - s, a2*s + p, s)
+    tf3 = TransferFunction(a0*p + p**a1 - s, p, p)
+    tf4 = TransferFunction(1, s**2 + 2*zeta*wn*s + wn**2, s)
+    inp = Function('X_d')(s)
+    out = Function('X')(s)
+
+    p0 = Parallel(tf, tf2)
+    assert p0.args == (tf, tf2)
+    assert p0.var == s
+
+    p1 = Parallel(Series(tf, -tf2), tf2)
+    assert p1.args == (Series(tf, -tf2), tf2)
+    assert p1.var == s
+
+    tf3_ = TransferFunction(inp, 1, s)
+    tf4_ = TransferFunction(-out, 1, s)
+    p2 = Parallel(tf, Series(tf3_, -tf4_), tf2)
+    assert p2.args == (tf, Series(tf3_, -tf4_), tf2)
+
+    p3 = Parallel(tf, tf2, tf4)
+    assert p3.args == (tf, tf2, tf4)
+
+    p4 = Parallel(tf3_, tf4_)
+    assert p4.args == (tf3_, tf4_)
+    assert p4.var == s
+
+    p5 = Parallel(tf, tf2)
+    assert p0 == p5
+    assert not p0 == p1
+
+    p6 = Parallel(tf2, tf4, Series(tf2, -tf4))
+    assert p6.args == (tf2, tf4, Series(tf2, -tf4))
+
+    p7 = Parallel(tf2, tf4, Series(tf2, -tf), tf4)
+    assert p7.args == (tf2, tf4, Series(tf2, -tf), tf4)
+
+    raises(ValueError, lambda: Parallel(tf, tf3))
+    raises(ValueError, lambda: Parallel(tf, tf2, tf3, tf4))
+    raises(ValueError, lambda: Parallel(-tf3, tf4))
+    raises(TypeError, lambda: Parallel(2, tf, tf4))
+    raises(TypeError, lambda: Parallel(s**2 + p*s, tf3, tf2))
+    raises(TypeError, lambda: Parallel(tf3, Matrix([1, 2, 3, 4])))
+
+
+def test_MIMOParallel_construction():
+    tfm1 = TransferFunctionMatrix([[TF1], [TF2], [TF3]])
+    tfm2 = TransferFunctionMatrix([[-TF3], [TF2], [TF1]])
+    tfm3 = TransferFunctionMatrix([[TF1]])
+    tfm4 = TransferFunctionMatrix([[TF2], [TF1], [TF3]])
+    tfm5 = TransferFunctionMatrix([[TF1, TF2], [TF2, TF1]])
+    tfm6 = TransferFunctionMatrix([[TF2, TF1], [TF1, TF2]])
+    tfm7 = TransferFunctionMatrix.from_Matrix(Matrix([[1/p]]), p)
+
+    p8 = MIMOParallel(tfm1, tfm2)
+    assert p8.args == (tfm1, tfm2)
+    assert p8.var == s
+    assert p8.shape == (p8.num_outputs, p8.num_inputs) == (3, 1)
+
+    p9 = MIMOParallel(MIMOSeries(tfm3, tfm1), tfm2)
+    assert p9.args == (MIMOSeries(tfm3, tfm1), tfm2)
+    assert p9.var == s
+    assert p9.shape == (p9.num_outputs, p9.num_inputs) == (3, 1)
+
+    p10 = MIMOParallel(tfm1, MIMOSeries(tfm3, tfm4), tfm2)
+    assert p10.args == (tfm1, MIMOSeries(tfm3, tfm4), tfm2)
+    assert p10.var == s
+    assert p10.shape == (p10.num_outputs, p10.num_inputs) == (3, 1)
+
+    p11 = MIMOParallel(tfm2, tfm1, tfm4)
+    assert p11.args == (tfm2, tfm1, tfm4)
+    assert p11.shape == (p11.num_outputs, p11.num_inputs) == (3, 1)
+
+    p12 = MIMOParallel(tfm6, tfm5)
+    assert p12.args == (tfm6, tfm5)
+    assert p12.shape == (p12.num_outputs, p12.num_inputs) == (2, 2)
+
+    p13 = MIMOParallel(tfm2, tfm4, MIMOSeries(-tfm3, tfm4), -tfm4)
+    assert p13.args == (tfm2, tfm4, MIMOSeries(-tfm3, tfm4), -tfm4)
+    assert p13.shape == (p13.num_outputs, p13.num_inputs) == (3, 1)
+
+    # arg cannot be empty tuple.
+    raises(TypeError, lambda: MIMOParallel(()))
+
+    # arg cannot contain SISO as well as MIMO systems.
+    raises(TypeError, lambda: MIMOParallel(tfm1, tfm2, TF1))
+
+    # all TFMs must have same shapes.
+    raises(TypeError, lambda: MIMOParallel(tfm1, tfm3, tfm4))
+
+    # all TFMs must be using the same complex variable.
+    raises(ValueError, lambda: MIMOParallel(tfm3, tfm7))
+
+    # Number or expression not allowed in the arguments.
+    raises(TypeError, lambda: MIMOParallel(2, tfm1, tfm4))
+    raises(TypeError, lambda: MIMOParallel(s**2 + p*s, -tfm4, tfm2))
+
+
+def test_Parallel_functions():
+    tf1 = TransferFunction(1, s**2 + 2*zeta*wn*s + wn**2, s)
+    tf2 = TransferFunction(k, 1, s)
+    tf3 = TransferFunction(a2*p - s, a2*s + p, s)
+    tf4 = TransferFunction(a0*p + p**a1 - s, p, p)
+    tf5 = TransferFunction(a1*s**2 + a2*s - a0, s + a0, s)
+
+    assert tf1 + tf2 + tf3 == Parallel(tf1, tf2, tf3)
+    assert tf1 + tf2 + tf3 + tf5 == Parallel(tf1, tf2, tf3, tf5)
+    assert tf1 + tf2 - tf3 - tf5 == Parallel(tf1, tf2, -tf3, -tf5)
+    assert tf1 + tf2*tf3 == Parallel(tf1, Series(tf2, tf3))
+    assert tf1 - tf2*tf3 == Parallel(tf1, -Series(tf2,tf3))
+    assert -tf1 - tf2 == Parallel(-tf1, -tf2)
+    assert -(tf1 + tf2) == Series(TransferFunction(-1, 1, s), Parallel(tf1, tf2))
+    assert (tf2 + tf3)*tf1 == Series(Parallel(tf2, tf3), tf1)
+    assert (tf1 + tf2)*(tf3*tf5) == Series(Parallel(tf1, tf2), tf3, tf5)
+    assert -(tf2 + tf3)*-tf5 == Series(TransferFunction(-1, 1, s), Parallel(tf2, tf3), -tf5)
+    assert tf2 + tf3 + tf2*tf1 + tf5 == Parallel(tf2, tf3, Series(tf2, tf1), tf5)
+    assert tf2 + tf3 + tf2*tf1 - tf3 == Parallel(tf2, tf3, Series(tf2, tf1), -tf3)
+    assert (tf1 + tf2 + tf5)*(tf3 + tf5) == Series(Parallel(tf1, tf2, tf5), Parallel(tf3, tf5))
+    raises(ValueError, lambda: tf1 + tf2 + tf4)
+    raises(ValueError, lambda: tf1 - tf2*tf4)
+    raises(ValueError, lambda: tf3 + Matrix([1, 2, 3]))
+
+    # evaluate=True -> doit()
+    assert Parallel(tf1, tf2, evaluate=True) == Parallel(tf1, tf2).doit() == \
+        TransferFunction(k*(s**2 + 2*s*wn*zeta + wn**2) + 1, s**2 + 2*s*wn*zeta + wn**2, s)
+    assert Parallel(tf1, tf2, Series(-tf1, tf3), evaluate=True) == \
+        Parallel(tf1, tf2, Series(-tf1, tf3)).doit() == TransferFunction(k*(a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2)**2 + \
+            (-a2*p + s)*(s**2 + 2*s*wn*zeta + wn**2) + (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), (a2*s + p)*(s**2 + \
+                2*s*wn*zeta + wn**2)**2, s)
+    assert Parallel(tf2, tf1, -tf3, evaluate=True) == Parallel(tf2, tf1, -tf3).doit() == \
+        TransferFunction(a2*s + k*(a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2) + p + (-a2*p + s)*(s**2 + 2*s*wn*zeta + wn**2) \
+            , (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), s)
+    assert not Parallel(tf1, -tf2, evaluate=False) == Parallel(tf1, -tf2).doit()
+
+    assert Parallel(Series(tf1, tf2), Series(tf2, tf3)).doit() == \
+        TransferFunction(k*(a2*p - s)*(s**2 + 2*s*wn*zeta + wn**2) + k*(a2*s + p), (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), s)
+    assert Parallel(-tf1, -tf2, -tf3).doit() == \
+        TransferFunction(-a2*s - k*(a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2) - p + (-a2*p + s)*(s**2 + 2*s*wn*zeta + wn**2), \
+            (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), s)
+    assert -Parallel(tf1, tf2, tf3).doit() == \
+        TransferFunction(-a2*s - k*(a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2) - p - (a2*p - s)*(s**2 + 2*s*wn*zeta + wn**2), \
+            (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), s)
+    assert Parallel(tf2, tf3, Series(tf2, -tf1), tf3).doit() == \
+        TransferFunction(k*(a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2) - k*(a2*s + p) + (2*a2*p - 2*s)*(s**2 + 2*s*wn*zeta \
+            + wn**2), (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), s)
+
+    assert Parallel(tf1, tf2).rewrite(TransferFunction) == \
+        TransferFunction(k*(s**2 + 2*s*wn*zeta + wn**2) + 1, s**2 + 2*s*wn*zeta + wn**2, s)
+    assert Parallel(tf2, tf1, -tf3).rewrite(TransferFunction) == \
+        TransferFunction(a2*s + k*(a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2) + p + (-a2*p + s)*(s**2 + 2*s*wn*zeta + \
+             wn**2), (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), s)
+
+    assert Parallel(tf1, Parallel(tf2, tf3)) == Parallel(tf1, tf2, tf3) == Parallel(Parallel(tf1, tf2), tf3)
+
+    P1 = Parallel(Series(tf1, tf2), Series(tf2, tf3))
+    assert P1.is_proper
+    assert not P1.is_strictly_proper
+    assert P1.is_biproper
+
+    P2 = Parallel(tf1, -tf2, -tf3)
+    assert P2.is_proper
+    assert not P2.is_strictly_proper
+    assert P2.is_biproper
+
+    P3 = Parallel(tf1, -tf2, Series(tf1, tf3))
+    assert P3.is_proper
+    assert not P3.is_strictly_proper
+    assert P3.is_biproper
+
+
+def test_MIMOParallel_functions():
+    tf4 = TransferFunction(a0*p + p**a1 - s, p, p)
+    tf5 = TransferFunction(a1*s**2 + a2*s - a0, s + a0, s)
+
+    tfm1 = TransferFunctionMatrix([[TF1], [TF2], [TF3]])
+    tfm2 = TransferFunctionMatrix([[-TF2], [tf5], [-TF1]])
+    tfm3 = TransferFunctionMatrix([[tf5], [-tf5], [TF2]])
+    tfm4 = TransferFunctionMatrix([[TF2, -tf5], [TF1, tf5]])
+    tfm5 = TransferFunctionMatrix([[TF1, TF2], [TF3, -tf5]])
+    tfm6 = TransferFunctionMatrix([[-TF2]])
+    tfm7 = TransferFunctionMatrix([[tf4], [-tf4], [tf4]])
+
+    assert tfm1 + tfm2 + tfm3 == MIMOParallel(tfm1, tfm2, tfm3) == MIMOParallel(MIMOParallel(tfm1, tfm2), tfm3)
+    assert tfm2 - tfm1 - tfm3 == MIMOParallel(tfm2, -tfm1, -tfm3)
+    assert tfm2 - tfm3 + (-tfm1*tfm6*-tfm6) == MIMOParallel(tfm2, -tfm3, MIMOSeries(-tfm6, tfm6, -tfm1))
+    assert tfm1 + tfm1 - (-tfm1*tfm6) == MIMOParallel(tfm1, tfm1, -MIMOSeries(tfm6, -tfm1))
+    assert tfm2 - tfm3 - tfm1 + tfm2 == MIMOParallel(tfm2, -tfm3, -tfm1, tfm2)
+    assert tfm1 + tfm2 - tfm3 - tfm1 == MIMOParallel(tfm1, tfm2, -tfm3, -tfm1)
+    raises(ValueError, lambda: tfm1 + tfm2 + TF2)
+    raises(TypeError, lambda: tfm1 - tfm2 - a1)
+    raises(TypeError, lambda: tfm2 - tfm3 - (s - 1))
+    raises(TypeError, lambda: -tfm3 - tfm2 - 9)
+    raises(TypeError, lambda: (1 - p**3) - tfm3 - tfm2)
+    # All TFMs must use the same complex var. tfm7 uses 'p'.
+    raises(ValueError, lambda: tfm3 - tfm2 - tfm7)
+    raises(ValueError, lambda: tfm2 - tfm1 + tfm7)
+    # (tfm1 +/- tfm2) has (3, 1) shape while tfm4 has (2, 2) shape.
+    raises(TypeError, lambda: tfm1 + tfm2 + tfm4)
+    raises(TypeError, lambda: (tfm1 - tfm2) - tfm4)
+
+    assert (tfm1 + tfm2)*tfm6 == MIMOSeries(tfm6, MIMOParallel(tfm1, tfm2))
+    assert (tfm2 - tfm3)*tfm6*-tfm6 == MIMOSeries(-tfm6, tfm6, MIMOParallel(tfm2, -tfm3))
+    assert (tfm2 - tfm1 - tfm3)*(tfm6 + tfm6) == MIMOSeries(MIMOParallel(tfm6, tfm6), MIMOParallel(tfm2, -tfm1, -tfm3))
+    raises(ValueError, lambda: (tfm4 + tfm5)*TF1)
+    raises(TypeError, lambda: (tfm2 - tfm3)*a2)
+    raises(TypeError, lambda: (tfm3 + tfm2)*(s - 6))
+    raises(TypeError, lambda: (tfm1 + tfm2 + tfm3)*0)
+    raises(TypeError, lambda: (1 - p**3)*(tfm1 + tfm3))
+
+    # (tfm3 - tfm2) has (3, 1) shape while tfm4*tfm5 has (2, 2) shape.
+    raises(ValueError, lambda: (tfm3 - tfm2)*tfm4*tfm5)
+    # (tfm1 - tfm2) has (3, 1) shape while tfm5 has (2, 2) shape.
+    raises(ValueError, lambda: (tfm1 - tfm2)*tfm5)
+
+    # TFM in the arguments.
+    assert (MIMOParallel(tfm1, tfm2, evaluate=True) == MIMOParallel(tfm1, tfm2).doit()
+    == MIMOParallel(tfm1, tfm2).rewrite(TransferFunctionMatrix)
+    == TransferFunctionMatrix(((TransferFunction(-k*(s**2 + 2*s*wn*zeta + wn**2) + 1, s**2 + 2*s*wn*zeta + wn**2, s),), \
+        (TransferFunction(-a0 + a1*s**2 + a2*s + k*(a0 + s), a0 + s, s),), (TransferFunction(-a2*s - p + (a2*p - s)* \
+        (s**2 + 2*s*wn*zeta + wn**2), (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), s),))))
+
+
+def test_Feedback_construction():
+    tf1 = TransferFunction(1, s**2 + 2*zeta*wn*s + wn**2, s)
+    tf2 = TransferFunction(k, 1, s)
+    tf3 = TransferFunction(a2*p - s, a2*s + p, s)
+    tf4 = TransferFunction(a0*p + p**a1 - s, p, p)
+    tf5 = TransferFunction(a1*s**2 + a2*s - a0, s + a0, s)
+    tf6 = TransferFunction(s - p, p + s, p)
+
+    f1 = Feedback(TransferFunction(1, 1, s), tf1*tf2*tf3)
+    assert f1.args == (TransferFunction(1, 1, s), Series(tf1, tf2, tf3), -1)
+    assert f1.sys1 == TransferFunction(1, 1, s)
+    assert f1.sys2 == Series(tf1, tf2, tf3)
+    assert f1.var == s
+
+    f2 = Feedback(tf1, tf2*tf3)
+    assert f2.args == (tf1, Series(tf2, tf3), -1)
+    assert f2.sys1 == tf1
+    assert f2.sys2 == Series(tf2, tf3)
+    assert f2.var == s
+
+    f3 = Feedback(tf1*tf2, tf5)
+    assert f3.args == (Series(tf1, tf2), tf5, -1)
+    assert f3.sys1 == Series(tf1, tf2)
+
+    f4 = Feedback(tf4, tf6)
+    assert f4.args == (tf4, tf6, -1)
+    assert f4.sys1 == tf4
+    assert f4.var == p
+
+    f5 = Feedback(tf5, TransferFunction(1, 1, s))
+    assert f5.args == (tf5, TransferFunction(1, 1, s), -1)
+    assert f5.var == s
+    assert f5 == Feedback(tf5)  # When sys2 is not passed explicitly, it is assumed to be unit tf.
+
+    f6 = Feedback(TransferFunction(1, 1, p), tf4)
+    assert f6.args == (TransferFunction(1, 1, p), tf4, -1)
+    assert f6.var == p
+
+    f7 = -Feedback(tf4*tf6, TransferFunction(1, 1, p))
+    assert f7.args == (Series(TransferFunction(-1, 1, p), Series(tf4, tf6)), -TransferFunction(1, 1, p), -1)
+    assert f7.sys1 == Series(TransferFunction(-1, 1, p), Series(tf4, tf6))
+
+    # denominator can't be a Parallel instance
+    raises(TypeError, lambda: Feedback(tf1, tf2 + tf3))
+    raises(TypeError, lambda: Feedback(tf1, Matrix([1, 2, 3])))
+    raises(TypeError, lambda: Feedback(TransferFunction(1, 1, s), s - 1))
+    raises(TypeError, lambda: Feedback(1, 1))
+    # raises(ValueError, lambda: Feedback(TransferFunction(1, 1, s), TransferFunction(1, 1, s)))
+    raises(ValueError, lambda: Feedback(tf2, tf4*tf5))
+    raises(ValueError, lambda: Feedback(tf2, tf1, 1.5))  # `sign` can only be -1 or 1
+    raises(ValueError, lambda: Feedback(tf1, -tf1**-1))  # denominator can't be zero
+    raises(ValueError, lambda: Feedback(tf4, tf5))  # Both systems should use the same `var`
+
+
+def test_Feedback_functions():
+    tf = TransferFunction(1, 1, s)
+    tf1 = TransferFunction(1, s**2 + 2*zeta*wn*s + wn**2, s)
+    tf2 = TransferFunction(k, 1, s)
+    tf3 = TransferFunction(a2*p - s, a2*s + p, s)
+    tf4 = TransferFunction(a0*p + p**a1 - s, p, p)
+    tf5 = TransferFunction(a1*s**2 + a2*s - a0, s + a0, s)
+    tf6 = TransferFunction(s - p, p + s, p)
+
+    assert (tf1*tf2*tf3 / tf3*tf5) == Series(tf1, tf2, tf3, pow(tf3, -1), tf5)
+    assert (tf1*tf2*tf3) / (tf3*tf5) == Series((tf1*tf2*tf3).doit(), pow((tf3*tf5).doit(),-1))
+    assert tf / (tf + tf1) == Feedback(tf, tf1)
+    assert tf / (tf + tf1*tf2*tf3) == Feedback(tf, tf1*tf2*tf3)
+    assert tf1 / (tf + tf1*tf2*tf3) == Feedback(tf1, tf2*tf3)
+    assert (tf1*tf2) / (tf + tf1*tf2) == Feedback(tf1*tf2, tf)
+    assert (tf1*tf2) / (tf + tf1*tf2*tf5) == Feedback(tf1*tf2, tf5)
+    assert (tf1*tf2) / (tf + tf1*tf2*tf5*tf3) in (Feedback(tf1*tf2, tf5*tf3), Feedback(tf1*tf2, tf3*tf5))
+    assert tf4 / (TransferFunction(1, 1, p) + tf4*tf6) == Feedback(tf4, tf6)
+    assert tf5 / (tf + tf5) == Feedback(tf5, tf)
+
+    raises(TypeError, lambda: tf1*tf2*tf3 / (1 + tf1*tf2*tf3))
+    raises(ValueError, lambda: tf2*tf3 / (tf + tf2*tf3*tf4))
+
+    assert Feedback(tf, tf1*tf2*tf3).doit() == \
+        TransferFunction((a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), k*(a2*p - s) + \
+        (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), s)
+    assert Feedback(tf, tf1*tf2*tf3).sensitivity == \
+        1/(k*(a2*p - s)/((a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2)) + 1)
+    assert Feedback(tf1, tf2*tf3).doit() == \
+        TransferFunction((a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2), (k*(a2*p - s) + \
+        (a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2))*(s**2 + 2*s*wn*zeta + wn**2), s)
+    assert Feedback(tf1, tf2*tf3).sensitivity == \
+        1/(k*(a2*p - s)/((a2*s + p)*(s**2 + 2*s*wn*zeta + wn**2)) + 1)
+    assert Feedback(tf1*tf2, tf5).doit() == \
+        TransferFunction(k*(a0 + s)*(s**2 + 2*s*wn*zeta + wn**2), (k*(-a0 + a1*s**2 + a2*s) + \
+        (a0 + s)*(s**2 + 2*s*wn*zeta + wn**2))*(s**2 + 2*s*wn*zeta + wn**2), s)
+    assert Feedback(tf1*tf2, tf5, 1).sensitivity == \
+        1/(-k*(-a0 + a1*s**2 + a2*s)/((a0 + s)*(s**2 + 2*s*wn*zeta + wn**2)) + 1)
+    assert Feedback(tf4, tf6).doit() == \
+        TransferFunction(p*(p + s)*(a0*p + p**a1 - s), p*(p*(p + s) + (-p + s)*(a0*p + p**a1 - s)), p)
+    assert -Feedback(tf4*tf6, TransferFunction(1, 1, p)).doit() == \
+        TransferFunction(-p*(-p + s)*(p + s)*(a0*p + p**a1 - s), p*(p + s)*(p*(p + s) + (-p + s)*(a0*p + p**a1 - s)), p)
+    assert Feedback(tf, tf).doit() == TransferFunction(1, 2, s)
+
+    assert Feedback(tf1, tf2*tf5).rewrite(TransferFunction) == \
+        TransferFunction((a0 + s)*(s**2 + 2*s*wn*zeta + wn**2), (k*(-a0 + a1*s**2 + a2*s) + \
+        (a0 + s)*(s**2 + 2*s*wn*zeta + wn**2))*(s**2 + 2*s*wn*zeta + wn**2), s)
+    assert Feedback(TransferFunction(1, 1, p), tf4).rewrite(TransferFunction) == \
+        TransferFunction(p, a0*p + p + p**a1 - s, p)
+
+
+def test_Feedback_as_TransferFunction():
+    # Solves issue https://github.com/sympy/sympy/issues/26161
+    tf1 = TransferFunction(s+1, 1, s)
+    tf2 = TransferFunction(s+2, 1, s)
+    fd1 = Feedback(tf1, tf2, -1) # Negative Feedback system
+    fd2 = Feedback(tf1, tf2, 1) # Positive Feedback system
+    unit = TransferFunction(1, 1, s)
+
+    # Checking the type
+    assert isinstance(fd1, TransferFunction)
+    assert isinstance(fd1, Feedback)
+
+    # Testing the numerator and denominator
+    assert fd1.num == tf1
+    assert fd2.num == tf1
+    assert fd1.den == Parallel(unit, Series(tf2, tf1))
+    assert fd2.den == Parallel(unit, -Series(tf2, tf1))
+
+    # Testing the Series and Parallel Combination with Feedback and TransferFunction
+    s1 = Series(tf1, fd1)
+    p1 = Parallel(tf1, fd1)
+    assert tf1 * fd1 == s1
+    assert tf1 + fd1 == p1
+    assert s1.doit() == TransferFunction((s + 1)**2, (s + 1)*(s + 2) + 1, s)
+    assert p1.doit() == TransferFunction(s + (s + 1)*((s + 1)*(s + 2) + 1) + 1, (s + 1)*(s + 2) + 1, s)
+
+    # Testing the use of Feedback and TransferFunction with Feedback
+    fd3 = Feedback(tf1*fd1, tf2, -1)
+    assert fd3 == Feedback(Series(tf1, fd1), tf2)
+    assert fd3.num == tf1 * fd1
+    assert fd3.den == Parallel(unit, Series(tf2, Series(tf1, fd1)))
+
+    # Testing the use of Feedback and TransferFunction with TransferFunction
+    tf3 = TransferFunction(tf1*fd1, tf2, s)
+    assert tf3 == TransferFunction(Series(tf1, fd1), tf2, s)
+    assert tf3.num == tf1*fd1
+
+def test_issue_26161():
+    # Issue https://github.com/sympy/sympy/issues/26161
+    Ib, Is, m, h, l2, l1 = symbols('I_b, I_s, m, h, l2, l1',
+                                            real=True, nonnegative=True)
+    KD, KP, v = symbols('K_D, K_P, v', real=True)
+
+    tau1_sq = (Ib + m * h ** 2) / m / g / h
+    tau2 = l2 / v
+    tau3 = v / (l1 + l2)
+    K = v ** 2 / g / (l1 + l2)
+
+    Gtheta = TransferFunction(-K * (tau2 * s + 1), tau1_sq * s ** 2 - 1, s)
+    Gdelta = TransferFunction(1, Is * s ** 2 + c * s, s)
+    Gpsi = TransferFunction(1, tau3 * s, s)
+    Dcont = TransferFunction(KD * s, 1, s)
+    PIcont = TransferFunction(KP, s, s)
+    Gunity = TransferFunction(1, 1, s)
+
+    Ginner = Feedback(Dcont * Gdelta, Gtheta)
+    Gouter = Feedback(PIcont * Ginner * Gpsi, Gunity)
+    assert Gouter == Feedback(Series(PIcont, Series(Ginner, Gpsi)), Gunity)
+    assert Gouter.num == Series(PIcont, Series(Ginner, Gpsi))
+    assert Gouter.den == Parallel(Gunity, Series(Gunity, Series(PIcont, Series(Ginner, Gpsi))))
+    expr = (KD*KP*g*s**3*v**2*(l1 + l2)*(Is*s**2 + c*s)**2*(-g*h*m + s**2*(Ib + h**2*m))*(-KD*g*h*m*s*v**2*(l2*s + v) + \
+            g*v*(l1 + l2)*(Is*s**2 + c*s)*(-g*h*m + s**2*(Ib + h**2*m))))/((s**2*v*(Is*s**2 + c*s)*(-KD*g*h*m*s*v**2* \
+            (l2*s + v) + g*v*(l1 + l2)*(Is*s**2 + c*s)*(-g*h*m + s**2*(Ib + h**2*m)))*(KD*KP*g*s*v*(l1 + l2)**2* \
+            (Is*s**2 + c*s)*(-g*h*m + s**2*(Ib + h**2*m)) + s**2*v*(Is*s**2 + c*s)*(-KD*g*h*m*s*v**2*(l2*s + v) + \
+            g*v*(l1 + l2)*(Is*s**2 + c*s)*(-g*h*m + s**2*(Ib + h**2*m))))/(l1 + l2)))
+
+    assert (Gouter.to_expr() - expr).simplify() == 0
+
+
+def test_MIMOFeedback_construction():
+    tf1 = TransferFunction(1, s, s)
+    tf2 = TransferFunction(s, s**3 - 1, s)
+    tf3 = TransferFunction(s, s + 1, s)
+    tf4 = TransferFunction(s, s**2 + 1, s)
+
+    tfm_1 = TransferFunctionMatrix([[tf1, tf2], [tf3, tf4]])
+    tfm_2 = TransferFunctionMatrix([[tf2, tf3], [tf4, tf1]])
+    tfm_3 = TransferFunctionMatrix([[tf3, tf4], [tf1, tf2]])
+
+    f1 = MIMOFeedback(tfm_1, tfm_2)
+    assert f1.args == (tfm_1, tfm_2, -1)
+    assert f1.sys1 == tfm_1
+    assert f1.sys2 == tfm_2
+    assert f1.var == s
+    assert f1.sign == -1
+    assert -(-f1) == f1
+
+    f2 = MIMOFeedback(tfm_2, tfm_1, 1)
+    assert f2.args == (tfm_2, tfm_1, 1)
+    assert f2.sys1 == tfm_2
+    assert f2.sys2 == tfm_1
+    assert f2.var == s
+    assert f2.sign == 1
+
+    f3 = MIMOFeedback(tfm_1, MIMOSeries(tfm_3, tfm_2))
+    assert f3.args == (tfm_1, MIMOSeries(tfm_3, tfm_2), -1)
+    assert f3.sys1 == tfm_1
+    assert f3.sys2 == MIMOSeries(tfm_3, tfm_2)
+    assert f3.var == s
+    assert f3.sign == -1
+
+    mat = Matrix([[1, 1/s], [0, 1]])
+    sys1 = controller = TransferFunctionMatrix.from_Matrix(mat, s)
+    f4 = MIMOFeedback(sys1, controller)
+    assert f4.args == (sys1, controller, -1)
+    assert f4.sys1 == f4.sys2 == sys1
+
+
+def test_MIMOFeedback_errors():
+    tf1 = TransferFunction(1, s, s)
+    tf2 = TransferFunction(s, s**3 - 1, s)
+    tf3 = TransferFunction(s, s - 1, s)
+    tf4 = TransferFunction(s, s**2 + 1, s)
+    tf5 = TransferFunction(1, 1, s)
+    tf6 = TransferFunction(-1, s - 1, s)
+
+    tfm_1 = TransferFunctionMatrix([[tf1, tf2], [tf3, tf4]])
+    tfm_2 = TransferFunctionMatrix([[tf2, tf3], [tf4, tf1]])
+    tfm_3 = TransferFunctionMatrix.from_Matrix(eye(2), var=s)
+    tfm_4 = TransferFunctionMatrix([[tf1, tf5], [tf5, tf5]])
+    tfm_5 = TransferFunctionMatrix([[-tf3, tf3], [tf3, tf6]])
+    # tfm_4 is inverse of tfm_5. Therefore tfm_5*tfm_4 = I
+    tfm_6 = TransferFunctionMatrix([[-tf3]])
+    tfm_7 = TransferFunctionMatrix([[tf3, tf4]])
+
+    # Unsupported Types
+    raises(TypeError, lambda: MIMOFeedback(tf1, tf2))
+    raises(TypeError, lambda: MIMOFeedback(MIMOParallel(tfm_1, tfm_2), tfm_3))
+    # Shape Errors
+    raises(ValueError, lambda: MIMOFeedback(tfm_1, tfm_6, 1))
+    raises(ValueError, lambda: MIMOFeedback(tfm_7, tfm_7))
+    # sign not 1/-1
+    raises(ValueError, lambda: MIMOFeedback(tfm_1, tfm_2, -2))
+    # Non-Invertible Systems
+    raises(ValueError, lambda: MIMOFeedback(tfm_5, tfm_4, 1))
+    raises(ValueError, lambda: MIMOFeedback(tfm_4, -tfm_5))
+    raises(ValueError, lambda: MIMOFeedback(tfm_3, tfm_3, 1))
+    # Variable not same in both the systems
+    tfm_8 = TransferFunctionMatrix.from_Matrix(eye(2), var=p)
+    raises(ValueError, lambda: MIMOFeedback(tfm_1, tfm_8, 1))
+
+
+def test_MIMOFeedback_functions():
+    tf1 = TransferFunction(1, s, s)
+    tf2 = TransferFunction(s, s - 1, s)
+    tf3 = TransferFunction(1, 1, s)
+    tf4 = TransferFunction(-1, s - 1, s)
+
+    tfm_1 = TransferFunctionMatrix.from_Matrix(eye(2), var=s)
+    tfm_2 = TransferFunctionMatrix([[tf1, tf3], [tf3, tf3]])
+    tfm_3 = TransferFunctionMatrix([[-tf2, tf2], [tf2, tf4]])
+    tfm_4 = TransferFunctionMatrix([[tf1, tf2], [-tf2, tf1]])
+
+    # sensitivity, doit(), rewrite()
+    F_1 = MIMOFeedback(tfm_2, tfm_3)
+    F_2 = MIMOFeedback(tfm_2, MIMOSeries(tfm_4, -tfm_1), 1)
+
+    assert F_1.sensitivity == Matrix([[S.Half, 0], [0, S.Half]])
+    assert F_2.sensitivity == Matrix([[(-2*s**4 + s**2)/(s**2 - s + 1),
+        (2*s**3 - s**2)/(s**2 - s + 1)], [-s**2, s]])
+
+    assert F_1.doit() == \
+        TransferFunctionMatrix(((TransferFunction(1, 2*s, s),
+        TransferFunction(1, 2, s)), (TransferFunction(1, 2, s),
+        TransferFunction(1, 2, s)))) == F_1.rewrite(TransferFunctionMatrix)
+    assert F_2.doit(cancel=False, expand=True) == \
+        TransferFunctionMatrix(((TransferFunction(-s**5 + 2*s**4 - 2*s**3 + s**2, s**5 - 2*s**4 + 3*s**3 - 2*s**2 + s, s),
+        TransferFunction(-2*s**4 + 2*s**3, s**2 - s + 1, s)), (TransferFunction(0, 1, s), TransferFunction(-s**2 + s, 1, s))))
+    assert F_2.doit(cancel=False) == \
+        TransferFunctionMatrix(((TransferFunction(s*(2*s**3 - s**2)*(s**2 - s + 1) + \
+        (-2*s**4 + s**2)*(s**2 - s + 1), s*(s**2 - s + 1)**2, s), TransferFunction(-2*s**4 + 2*s**3, s**2 - s + 1, s)),
+        (TransferFunction(0, 1, s), TransferFunction(-s**2 + s, 1, s))))
+    assert F_2.doit() == \
+        TransferFunctionMatrix(((TransferFunction(s*(-2*s**2 + s*(2*s - 1) + 1), s**2 - s + 1, s),
+        TransferFunction(-2*s**3*(s - 1), s**2 - s + 1, s)), (TransferFunction(0, 1, s), TransferFunction(s*(1 - s), 1, s))))
+    assert F_2.doit(expand=True) == \
+        TransferFunctionMatrix(((TransferFunction(-s**2 + s, s**2 - s + 1, s), TransferFunction(-2*s**4 + 2*s**3, s**2 - s + 1, s)),
+        (TransferFunction(0, 1, s), TransferFunction(-s**2 + s, 1, s))))
+
+    assert -(F_1.doit()) == (-F_1).doit()  # First negating then calculating vs calculating then negating.
+
+
+def test_TransferFunctionMatrix_construction():
+    tf5 = TransferFunction(a1*s**2 + a2*s - a0, s + a0, s)
+    tf4 = TransferFunction(a0*p + p**a1 - s, p, p)
+
+    tfm3_ = TransferFunctionMatrix([[-TF3]])
+    assert tfm3_.shape == (tfm3_.num_outputs, tfm3_.num_inputs) == (1, 1)
+    assert tfm3_.args == Tuple(Tuple(Tuple(-TF3)))
+    assert tfm3_.var == s
+
+    tfm5 = TransferFunctionMatrix([[TF1, -TF2], [TF3, tf5]])
+    assert tfm5.shape == (tfm5.num_outputs, tfm5.num_inputs) == (2, 2)
+    assert tfm5.args == Tuple(Tuple(Tuple(TF1, -TF2), Tuple(TF3, tf5)))
+    assert tfm5.var == s
+
+    tfm7 = TransferFunctionMatrix([[TF1, TF2], [TF3, -tf5], [-tf5, TF2]])
+    assert tfm7.shape == (tfm7.num_outputs, tfm7.num_inputs) == (3, 2)
+    assert tfm7.args == Tuple(Tuple(Tuple(TF1, TF2), Tuple(TF3, -tf5), Tuple(-tf5, TF2)))
+    assert tfm7.var == s
+
+    # all transfer functions will use the same complex variable. tf4 uses 'p'.
+    raises(ValueError, lambda: TransferFunctionMatrix([[TF1], [TF2], [tf4]]))
+    raises(ValueError, lambda: TransferFunctionMatrix([[TF1, tf4], [TF3, tf5]]))
+
+    # length of all the lists in the TFM should be equal.
+    raises(ValueError, lambda: TransferFunctionMatrix([[TF1], [TF3, tf5]]))
+    raises(ValueError, lambda: TransferFunctionMatrix([[TF1, TF3], [tf5]]))
+
+    # lists should only support transfer functions in them.
+    raises(TypeError, lambda: TransferFunctionMatrix([[TF1, TF2], [TF3, Matrix([1, 2])]]))
+    raises(TypeError, lambda: TransferFunctionMatrix([[TF1, Matrix([1, 2])], [TF3, TF2]]))
+
+    # `arg` should strictly be nested list of TransferFunction
+    raises(ValueError, lambda: TransferFunctionMatrix([TF1, TF2, tf5]))
+    raises(ValueError, lambda: TransferFunctionMatrix([TF1]))
+
+def test_TransferFunctionMatrix_functions():
+    tf5 = TransferFunction(a1*s**2 + a2*s - a0, s + a0, s)
+
+    #  Classmethod (from_matrix)
+
+    mat_1 = ImmutableMatrix([
+        [s*(s + 1)*(s - 3)/(s**4 + 1), 2],
+        [p, p*(s + 1)/(s*(s**1 + 1))]
+        ])
+    mat_2 = ImmutableMatrix([[(2*s + 1)/(s**2 - 9)]])
+    mat_3 = ImmutableMatrix([[1, 2], [3, 4]])
+    assert TransferFunctionMatrix.from_Matrix(mat_1, s) == \
+        TransferFunctionMatrix([[TransferFunction(s*(s - 3)*(s + 1), s**4 + 1, s), TransferFunction(2, 1, s)],
+        [TransferFunction(p, 1, s), TransferFunction(p, s, s)]])
+    assert TransferFunctionMatrix.from_Matrix(mat_2, s) == \
+        TransferFunctionMatrix([[TransferFunction(2*s + 1, s**2 - 9, s)]])
+    assert TransferFunctionMatrix.from_Matrix(mat_3, p) == \
+        TransferFunctionMatrix([[TransferFunction(1, 1, p), TransferFunction(2, 1, p)],
+        [TransferFunction(3, 1, p), TransferFunction(4, 1, p)]])
+
+    #  Negating a TFM
+
+    tfm1 = TransferFunctionMatrix([[TF1], [TF2]])
+    assert -tfm1 == TransferFunctionMatrix([[-TF1], [-TF2]])
+
+    tfm2 = TransferFunctionMatrix([[TF1, TF2, TF3], [tf5, -TF1, -TF3]])
+    assert -tfm2 == TransferFunctionMatrix([[-TF1, -TF2, -TF3], [-tf5, TF1, TF3]])
+
+    # subs()
+
+    H_1 = TransferFunctionMatrix.from_Matrix(mat_1, s)
+    H_2 = TransferFunctionMatrix([[TransferFunction(a*p*s, k*s**2, s), TransferFunction(p*s, k*(s**2 - a), s)]])
+    assert H_1.subs(p, 1) == TransferFunctionMatrix([[TransferFunction(s*(s - 3)*(s + 1), s**4 + 1, s), TransferFunction(2, 1, s)], [TransferFunction(1, 1, s), TransferFunction(1, s, s)]])
+    assert H_1.subs({p: 1}) == TransferFunctionMatrix([[TransferFunction(s*(s - 3)*(s + 1), s**4 + 1, s), TransferFunction(2, 1, s)], [TransferFunction(1, 1, s), TransferFunction(1, s, s)]])
+    assert H_1.subs({p: 1, s: 1}) == TransferFunctionMatrix([[TransferFunction(s*(s - 3)*(s + 1), s**4 + 1, s), TransferFunction(2, 1, s)], [TransferFunction(1, 1, s), TransferFunction(1, s, s)]]) # This should ignore `s` as it is `var`
+    assert H_2.subs(p, 2) == TransferFunctionMatrix([[TransferFunction(2*a*s, k*s**2, s), TransferFunction(2*s, k*(-a + s**2), s)]])
+    assert H_2.subs(k, 1) == TransferFunctionMatrix([[TransferFunction(a*p*s, s**2, s), TransferFunction(p*s, -a + s**2, s)]])
+    assert H_2.subs(a, 0) == TransferFunctionMatrix([[TransferFunction(0, k*s**2, s), TransferFunction(p*s, k*s**2, s)]])
+    assert H_2.subs({p: 1, k: 1, a: a0}) == TransferFunctionMatrix([[TransferFunction(a0*s, s**2, s), TransferFunction(s, -a0 + s**2, s)]])
+
+    # eval_frequency()
+    assert H_2.eval_frequency(S(1)/2 + I) == Matrix([[2*a*p/(5*k) - 4*I*a*p/(5*k), I*p/(-a*k - 3*k/4 + I*k) + p/(-2*a*k - 3*k/2 + 2*I*k)]])
+
+    # transpose()
+
+    assert H_1.transpose() == TransferFunctionMatrix([[TransferFunction(s*(s - 3)*(s + 1), s**4 + 1, s), TransferFunction(p, 1, s)], [TransferFunction(2, 1, s), TransferFunction(p, s, s)]])
+    assert H_2.transpose() == TransferFunctionMatrix([[TransferFunction(a*p*s, k*s**2, s)], [TransferFunction(p*s, k*(-a + s**2), s)]])
+    assert H_1.transpose().transpose() == H_1
+    assert H_2.transpose().transpose() == H_2
+
+    # elem_poles()
+
+    assert H_1.elem_poles() == [[[-sqrt(2)/2 - sqrt(2)*I/2, -sqrt(2)/2 + sqrt(2)*I/2, sqrt(2)/2 - sqrt(2)*I/2, sqrt(2)/2 + sqrt(2)*I/2], []],
+        [[], [0]]]
+    assert H_2.elem_poles() == [[[0, 0], [sqrt(a), -sqrt(a)]]]
+    assert tfm2.elem_poles() == [[[wn*(-zeta + sqrt((zeta - 1)*(zeta + 1))), wn*(-zeta - sqrt((zeta - 1)*(zeta + 1)))], [], [-p/a2]],
+        [[-a0], [wn*(-zeta + sqrt((zeta - 1)*(zeta + 1))), wn*(-zeta - sqrt((zeta - 1)*(zeta + 1)))], [-p/a2]]]
+
+    # elem_zeros()
+
+    assert H_1.elem_zeros() == [[[-1, 0, 3], []], [[], []]]
+    assert H_2.elem_zeros() == [[[0], [0]]]
+    assert tfm2.elem_zeros() == [[[], [], [a2*p]],
+        [[-a2/(2*a1) - sqrt(4*a0*a1 + a2**2)/(2*a1), -a2/(2*a1) + sqrt(4*a0*a1 + a2**2)/(2*a1)], [], [a2*p]]]
+
+    # doit()
+
+    H_3 = TransferFunctionMatrix([[Series(TransferFunction(1, s**3 - 3, s), TransferFunction(s**2 - 2*s + 5, 1, s), TransferFunction(1, s, s))]])
+    H_4 = TransferFunctionMatrix([[Parallel(TransferFunction(s**3 - 3, 4*s**4 - s**2 - 2*s + 5, s), TransferFunction(4 - s**3, 4*s**4 - s**2 - 2*s + 5, s))]])
+
+    assert H_3.doit() == TransferFunctionMatrix([[TransferFunction(s**2 - 2*s + 5, s*(s**3 - 3), s)]])
+    assert H_4.doit() == TransferFunctionMatrix([[TransferFunction(1, 4*s**4 - s**2 - 2*s + 5, s)]])
+
+    # _flat()
+
+    assert H_1._flat() == [TransferFunction(s*(s - 3)*(s + 1), s**4 + 1, s), TransferFunction(2, 1, s), TransferFunction(p, 1, s), TransferFunction(p, s, s)]
+    assert H_2._flat() == [TransferFunction(a*p*s, k*s**2, s), TransferFunction(p*s, k*(-a + s**2), s)]
+    assert H_3._flat() == [Series(TransferFunction(1, s**3 - 3, s), TransferFunction(s**2 - 2*s + 5, 1, s), TransferFunction(1, s, s))]
+    assert H_4._flat() == [Parallel(TransferFunction(s**3 - 3, 4*s**4 - s**2 - 2*s + 5, s), TransferFunction(4 - s**3, 4*s**4 - s**2 - 2*s + 5, s))]
+
+    # evalf()
+
+    assert H_1.evalf() == \
+        TransferFunctionMatrix(((TransferFunction(s*(s - 3.0)*(s + 1.0), s**4 + 1.0, s), TransferFunction(2.0, 1, s)), (TransferFunction(1.0*p, 1, s), TransferFunction(p, s, s))))
+    assert H_2.subs({a:3.141, p:2.88, k:2}).evalf() == \
+        TransferFunctionMatrix(((TransferFunction(4.5230399999999999494093572138808667659759521484375, s, s),
+        TransferFunction(2.87999999999999989341858963598497211933135986328125*s, 2.0*s**2 - 6.282000000000000028421709430404007434844970703125, s)),))
+
+    # simplify()
+
+    H_5 = TransferFunctionMatrix([[TransferFunction(s**5 + s**3 + s, s - s**2, s),
+        TransferFunction((s + 3)*(s - 1), (s - 1)*(s + 5), s)]])
+
+    assert H_5.simplify() == simplify(H_5) == \
+        TransferFunctionMatrix(((TransferFunction(-s**4 - s**2 - 1, s - 1, s), TransferFunction(s + 3, s + 5, s)),))
+
+    # expand()
+
+    assert (H_1.expand()
+            == TransferFunctionMatrix(((TransferFunction(s**3 - 2*s**2 - 3*s, s**4 + 1, s), TransferFunction(2, 1, s)),
+            (TransferFunction(p, 1, s), TransferFunction(p, s, s)))))
+    assert H_5.expand() == \
+        TransferFunctionMatrix(((TransferFunction(s**5 + s**3 + s, -s**2 + s, s), TransferFunction(s**2 + 2*s - 3, s**2 + 4*s - 5, s)),))
+
+def test_TransferFunction_gbt():
+    # simple transfer function, e.g. ohms law
+    tf = TransferFunction(1, a*s+b, s)
+    numZ, denZ = gbt(tf, T, 0.5)
+    # discretized transfer function with coefs from tf.gbt()
+    tf_test_bilinear = TransferFunction(s * numZ[0] + numZ[1], s * denZ[0] + denZ[1], s)
+    # corresponding tf with manually calculated coefs
+    tf_test_manual = TransferFunction(s * T/(2*(a + b*T/2)) + T/(2*(a + b*T/2)), s + (-a + b*T/2)/(a + b*T/2), s)
+
+    assert S.Zero == (tf_test_bilinear.simplify()-tf_test_manual.simplify()).simplify().num
+
+    tf = TransferFunction(1, a*s+b, s)
+    numZ, denZ = gbt(tf, T, 0)
+    # discretized transfer function with coefs from tf.gbt()
+    tf_test_forward = TransferFunction(numZ[0], s*denZ[0]+denZ[1], s)
+    # corresponding tf with manually calculated coefs
+    tf_test_manual = TransferFunction(T/a, s + (-a + b*T)/a, s)
+
+    assert S.Zero == (tf_test_forward.simplify()-tf_test_manual.simplify()).simplify().num
+
+    tf = TransferFunction(1, a*s+b, s)
+    numZ, denZ = gbt(tf, T, 1)
+    # discretized transfer function with coefs from tf.gbt()
+    tf_test_backward = TransferFunction(s*numZ[0], s*denZ[0]+denZ[1], s)
+    # corresponding tf with manually calculated coefs
+    tf_test_manual = TransferFunction(s * T/(a + b*T), s - a/(a + b*T), s)
+
+    assert S.Zero == (tf_test_backward.simplify()-tf_test_manual.simplify()).simplify().num
+
+    tf = TransferFunction(1, a*s+b, s)
+    numZ, denZ = gbt(tf, T, 0.3)
+    # discretized transfer function with coefs from tf.gbt()
+    tf_test_gbt = TransferFunction(s*numZ[0]+numZ[1], s*denZ[0]+denZ[1], s)
+    # corresponding tf with manually calculated coefs
+    tf_test_manual = TransferFunction(s*3*T/(10*(a + 3*b*T/10)) + 7*T/(10*(a + 3*b*T/10)), s + (-a + 7*b*T/10)/(a + 3*b*T/10), s)
+
+    assert S.Zero == (tf_test_gbt.simplify()-tf_test_manual.simplify()).simplify().num
+
+def test_TransferFunction_bilinear():
+    # simple transfer function, e.g. ohms law
+    tf = TransferFunction(1, a*s+b, s)
+    numZ, denZ = bilinear(tf, T)
+    # discretized transfer function with coefs from tf.bilinear()
+    tf_test_bilinear = TransferFunction(s*numZ[0]+numZ[1], s*denZ[0]+denZ[1], s)
+    # corresponding tf with manually calculated coefs
+    tf_test_manual = TransferFunction(s * T/(2*(a + b*T/2)) + T/(2*(a + b*T/2)), s + (-a + b*T/2)/(a + b*T/2), s)
+
+    assert S.Zero == (tf_test_bilinear.simplify()-tf_test_manual.simplify()).simplify().num
+
+def test_TransferFunction_forward_diff():
+    # simple transfer function, e.g. ohms law
+    tf = TransferFunction(1, a*s+b, s)
+    numZ, denZ = forward_diff(tf, T)
+    # discretized transfer function with coefs from tf.forward_diff()
+    tf_test_forward = TransferFunction(numZ[0], s*denZ[0]+denZ[1], s)
+    # corresponding tf with manually calculated coefs
+    tf_test_manual = TransferFunction(T/a, s + (-a + b*T)/a, s)
+
+    assert S.Zero == (tf_test_forward.simplify()-tf_test_manual.simplify()).simplify().num
+
+def test_TransferFunction_backward_diff():
+    # simple transfer function, e.g. ohms law
+    tf = TransferFunction(1, a*s+b, s)
+    numZ, denZ = backward_diff(tf, T)
+    # discretized transfer function with coefs from tf.backward_diff()
+    tf_test_backward = TransferFunction(s*numZ[0]+numZ[1], s*denZ[0]+denZ[1], s)
+    # corresponding tf with manually calculated coefs
+    tf_test_manual = TransferFunction(s * T/(a + b*T), s - a/(a + b*T), s)
+
+    assert S.Zero == (tf_test_backward.simplify()-tf_test_manual.simplify()).simplify().num
+
+def test_TransferFunction_phase_margin():
+    # Test for phase margin
+    tf1 = TransferFunction(10, p**3 + 1, p)
+    tf2 = TransferFunction(s**2, 10, s)
+    tf3 = TransferFunction(1, a*s+b, s)
+    tf4 = TransferFunction((s + 1)*exp(s/tau), s**2 + 2, s)
+    tf_m = TransferFunctionMatrix([[tf2],[tf3]])
+
+    assert phase_margin(tf1) == -180 + 180*atan(3*sqrt(11))/pi
+    assert phase_margin(tf2) == 0
+
+    raises(NotImplementedError, lambda: phase_margin(tf4))
+    raises(ValueError, lambda: phase_margin(tf3))
+    raises(ValueError, lambda: phase_margin(MIMOSeries(tf_m)))
+
+def test_TransferFunction_gain_margin():
+    # Test for gain margin
+    tf1 = TransferFunction(s**2, 5*(s+1)*(s-5)*(s-10), s)
+    tf2 = TransferFunction(s**2 + 2*s + 1, 1, s)
+    tf3 = TransferFunction(1, a*s+b, s)
+    tf4 = TransferFunction((s + 1)*exp(s/tau), s**2 + 2, s)
+    tf_m = TransferFunctionMatrix([[tf2],[tf3]])
+
+    assert gain_margin(tf1) == -20*log(S(7)/540)/log(10)
+    assert gain_margin(tf2) == oo
+
+    raises(NotImplementedError, lambda: gain_margin(tf4))
+    raises(ValueError, lambda: gain_margin(tf3))
+    raises(ValueError, lambda: gain_margin(MIMOSeries(tf_m)))
+
+
+def test_StateSpace_construction():
+    # using different numbers for a SISO system.
+    A1 = Matrix([[0, 1], [1, 0]])
+    B1 = Matrix([1, 0])
+    C1 = Matrix([[0, 1]])
+    D1 = Matrix([0])
+    ss1 = StateSpace(A1, B1, C1, D1)
+
+    assert ss1.state_matrix == Matrix([[0, 1], [1, 0]])
+    assert ss1.input_matrix == Matrix([1, 0])
+    assert ss1.output_matrix == Matrix([[0, 1]])
+    assert ss1.feedforward_matrix == Matrix([0])
+    assert ss1.args == (Matrix([[0, 1], [1, 0]]), Matrix([[1], [0]]), Matrix([[0, 1]]), Matrix([[0]]))
+
+    # using different symbols for a SISO system.
+    ss2 = StateSpace(Matrix([a0]), Matrix([a1]),
+                    Matrix([a2]), Matrix([a3]))
+
+    assert ss2.state_matrix == Matrix([[a0]])
+    assert ss2.input_matrix == Matrix([[a1]])
+    assert ss2.output_matrix == Matrix([[a2]])
+    assert ss2.feedforward_matrix == Matrix([[a3]])
+    assert ss2.args == (Matrix([[a0]]), Matrix([[a1]]), Matrix([[a2]]), Matrix([[a3]]))
+
+    # using different numbers for a MIMO system.
+    ss3 = StateSpace(Matrix([[-1.5, -2], [1, 0]]),
+                    Matrix([[0.5, 0], [0, 1]]),
+                    Matrix([[0, 1], [0, 2]]),
+                    Matrix([[2, 2], [1, 1]]))
+
+    assert ss3.state_matrix == Matrix([[-1.5, -2], [1,  0]])
+    assert ss3.input_matrix == Matrix([[0.5, 0], [0, 1]])
+    assert ss3.output_matrix == Matrix([[0, 1], [0, 2]])
+    assert ss3.feedforward_matrix == Matrix([[2, 2], [1, 1]])
+    assert ss3.args == (Matrix([[-1.5, -2],
+                                [1,  0]]),
+                        Matrix([[0.5, 0],
+                                [0, 1]]),
+                        Matrix([[0, 1],
+                                [0, 2]]),
+                        Matrix([[2, 2],
+                                [1, 1]]))
+
+    # using different symbols for a MIMO system.
+    A4 = Matrix([[a0, a1], [a2, a3]])
+    B4 = Matrix([[b0, b1], [b2, b3]])
+    C4 = Matrix([[c0, c1], [c2, c3]])
+    D4 = Matrix([[d0, d1], [d2, d3]])
+    ss4 = StateSpace(A4, B4, C4, D4)
+
+    assert ss4.state_matrix == Matrix([[a0, a1], [a2, a3]])
+    assert ss4.input_matrix == Matrix([[b0, b1], [b2, b3]])
+    assert ss4.output_matrix == Matrix([[c0, c1], [c2, c3]])
+    assert ss4.feedforward_matrix == Matrix([[d0, d1], [d2, d3]])
+    assert ss4.args == (Matrix([[a0, a1],
+                                [a2, a3]]),
+                        Matrix([[b0, b1],
+                                [b2, b3]]),
+                        Matrix([[c0, c1],
+                                [c2, c3]]),
+                        Matrix([[d0, d1],
+                                [d2, d3]]))
+
+    # using less matrices. Rest will be filled with a minimum of zeros.
+    ss5 = StateSpace()
+    assert ss5.args == (Matrix([[0]]), Matrix([[0]]), Matrix([[0]]), Matrix([[0]]))
+
+    A6 = Matrix([[0, 1], [1, 0]])
+    B6 = Matrix([1, 1])
+    ss6 = StateSpace(A6, B6)
+
+    assert ss6.state_matrix == Matrix([[0, 1], [1, 0]])
+    assert ss6.input_matrix ==  Matrix([1, 1])
+    assert ss6.output_matrix == Matrix([[0, 0]])
+    assert ss6.feedforward_matrix == Matrix([[0]])
+    assert ss6.args == (Matrix([[0, 1],
+                                [1, 0]]),
+                        Matrix([[1],
+                                [1]]),
+                        Matrix([[0, 0]]),
+                        Matrix([[0]]))
+
+    # Check if the system is SISO or MIMO.
+    # If system is not SISO, then it is definitely MIMO.
+
+    assert ss1.is_SISO == True
+    assert ss2.is_SISO == True
+    assert ss3.is_SISO == False
+    assert ss4.is_SISO == False
+    assert ss5.is_SISO == True
+    assert ss6.is_SISO == True
+
+    # ShapeError if matrices do not fit.
+    raises(ShapeError, lambda: StateSpace(Matrix([s, (s+1)**2]), Matrix([s+1]),
+                                          Matrix([s**2 - 1]), Matrix([2*s])))
+    raises(ShapeError, lambda: StateSpace(Matrix([s]), Matrix([s+1, s**3 + 1]),
+                                          Matrix([s**2 - 1]), Matrix([2*s])))
+    raises(ShapeError, lambda: StateSpace(Matrix([s]), Matrix([s+1]),
+                                          Matrix([[s**2 - 1], [s**2 + 2*s + 1]]), Matrix([2*s])))
+    raises(ShapeError, lambda: StateSpace(Matrix([[-s, -s], [s, 0]]),
+                                                Matrix([[s/2, 0], [0, s]]),
+                                                Matrix([[0, s]]),
+                                                Matrix([[2*s, 2*s], [s, s]])))
+
+    # TypeError if arguments are not sympy matrices.
+    raises(TypeError, lambda: StateSpace(s**2, s+1, 2*s, 1))
+    raises(TypeError, lambda: StateSpace(Matrix([2, 0.5]), Matrix([-1]),
+                                         Matrix([1]), 0))
+def test_StateSpace_add():
+    A1 = Matrix([[4, 1],[2, -3]])
+    B1 = Matrix([[5, 2],[-3, -3]])
+    C1 = Matrix([[2, -4],[0, 1]])
+    D1 = Matrix([[3, 2],[1, -1]])
+    ss1 = StateSpace(A1, B1, C1, D1)
+
+    A2 = Matrix([[-3, 4, 2],[-1, -3, 0],[2, 5, 3]])
+    B2 = Matrix([[1, 4],[-3, -3],[-2, 1]])
+    C2 = Matrix([[4, 2, -3],[1, 4, 3]])
+    D2 = Matrix([[-2, 4],[0, 1]])
+    ss2 = StateSpace(A2, B2, C2, D2)
+    ss3 = StateSpace()
+    ss4 = StateSpace(Matrix([1]), Matrix([2]), Matrix([3]), Matrix([4]))
+
+    expected_add = \
+        StateSpace(
+        Matrix([
+        [4,  1,  0,  0, 0],
+        [2, -3,  0,  0, 0],
+        [0,  0, -3,  4, 2],
+        [0,  0, -1, -3, 0],
+        [0,  0,  2,  5, 3]]),
+        Matrix([
+        [ 5,  2],
+        [-3, -3],
+        [ 1,  4],
+        [-3, -3],
+        [-2,  1]]),
+        Matrix([
+        [2, -4, 4, 2, -3],
+        [0,  1, 1, 4,  3]]),
+        Matrix([
+        [1, 6],
+        [1, 0]]))
+
+    expected_mul = \
+        StateSpace(
+        Matrix([
+        [ -3,   4,  2, 0,  0],
+        [ -1,  -3,  0, 0,  0],
+        [  2,   5,  3, 0,  0],
+        [ 22,  18, -9, 4,  1],
+        [-15, -18,  0, 2, -3]]),
+        Matrix([
+        [  1,   4],
+        [ -3,  -3],
+        [ -2,   1],
+        [-10,  22],
+        [  6, -15]]),
+        Matrix([
+        [14, 14, -3, 2, -4],
+        [ 3, -2, -6, 0,  1]]),
+        Matrix([
+        [-6, 14],
+        [-2,  3]]))
+
+    assert ss1 + ss2 == expected_add
+    assert ss1*ss2 == expected_mul
+    assert ss3 + 1/2 == StateSpace(Matrix([[0]]), Matrix([[0]]), Matrix([[0]]), Matrix([[0.5]]))
+    assert ss4*1.5 == StateSpace(Matrix([[1]]), Matrix([[2]]), Matrix([[4.5]]), Matrix([[6.0]]))
+    assert 1.5*ss4 == StateSpace(Matrix([[1]]), Matrix([[3.0]]), Matrix([[3]]), Matrix([[6.0]]))
+    raises(ShapeError, lambda: ss1 + ss3)
+    raises(ShapeError, lambda: ss2*ss4)
+
+def test_StateSpace_negation():
+    A = Matrix([[a0, a1], [a2, a3]])
+    B = Matrix([[b0, b1], [b2, b3]])
+    C = Matrix([[c0, c1], [c1, c2], [c2, c3]])
+    D = Matrix([[d0, d1], [d1, d2], [d2, d3]])
+    SS = StateSpace(A, B, C, D)
+    SS_neg = -SS
+
+    state_mat = Matrix([[-1, 1], [1, -1]])
+    input_mat = Matrix([1, -1])
+    output_mat = Matrix([[-1, 1]])
+    feedforward_mat = Matrix([1])
+    system = StateSpace(state_mat, input_mat, output_mat, feedforward_mat)
+
+    assert SS_neg == \
+        StateSpace(Matrix([[a0, a1],
+                           [a2, a3]]),
+                   Matrix([[b0, b1],
+                           [b2, b3]]),
+                   Matrix([[-c0, -c1],
+                           [-c1, -c2],
+                           [-c2, -c3]]),
+                   Matrix([[-d0, -d1],
+                           [-d1, -d2],
+                           [-d2, -d3]]))
+    assert -system == \
+        StateSpace(Matrix([[-1,  1],
+                           [ 1, -1]]),
+                   Matrix([[ 1],[-1]]),
+                   Matrix([[1, -1]]),
+                   Matrix([[-1]]))
+    assert -SS_neg == SS
+    assert -(-(-(-system))) == system
+
+def test_SymPy_substitution_functions():
+    # subs
+    ss1 = StateSpace(Matrix([s]), Matrix([(s + 1)**2]), Matrix([s**2 - 1]), Matrix([2*s]))
+    ss2 = StateSpace(Matrix([s + p]), Matrix([(s + 1)*(p - 1)]), Matrix([p**3 - s**3]), Matrix([s - p]))
+
+    assert ss1.subs({s:5}) == StateSpace(Matrix([[5]]), Matrix([[36]]), Matrix([[24]]), Matrix([[10]]))
+    assert ss2.subs({p:1}) == StateSpace(Matrix([[s + 1]]), Matrix([[0]]), Matrix([[1 - s**3]]), Matrix([[s - 1]]))
+
+    # xreplace
+    assert ss1.xreplace({s:p}) == \
+        StateSpace(Matrix([[p]]), Matrix([[(p + 1)**2]]), Matrix([[p**2 - 1]]), Matrix([[2*p]]))
+    assert ss2.xreplace({s:a, p:b}) == \
+        StateSpace(Matrix([[a + b]]), Matrix([[(a + 1)*(b - 1)]]), Matrix([[-a**3 + b**3]]), Matrix([[a - b]]))
+
+    # evalf
+    p1 = a1*s + a0
+    p2 = b2*s**2 + b1*s + b0
+    G = StateSpace(Matrix([p1]), Matrix([p2]))
+    expect = StateSpace(Matrix([[2*s + 1]]), Matrix([[5*s**2 + 4*s + 3]]), Matrix([[0]]), Matrix([[0]]))
+    expect_ = StateSpace(Matrix([[2.0*s + 1.0]]), Matrix([[5.0*s**2 + 4.0*s + 3.0]]), Matrix([[0]]), Matrix([[0]]))
+    assert G.subs({a0: 1, a1: 2, b0: 3, b1: 4, b2: 5}) == expect
+    assert G.subs({a0: 1, a1: 2, b0: 3, b1: 4, b2: 5}).evalf() == expect_
+    assert expect.evalf() == expect_
+
+def test_conversion():
+    # StateSpace to TransferFunction for SISO
+    A1 = Matrix([[-5, -1], [3, -1]])
+    B1 = Matrix([2, 5])
+    C1 = Matrix([[1, 2]])
+    D1 = Matrix([0])
+    H1 = StateSpace(A1, B1, C1, D1)
+    tm1 = H1.rewrite(TransferFunction)
+    tm2 = (-H1).rewrite(TransferFunction)
+
+    tf1 = tm1[0][0]
+    tf2 = tm2[0][0]
+
+    assert tf1 == TransferFunction(12*s + 59, s**2 + 6*s + 8, s)
+    assert tf2.num == -tf1.num
+    assert tf2.den == tf1.den
+
+    # StateSpace to TransferFunction for MIMO
+    A2 = Matrix([[-1.5, -2, 3], [1, 0, 1], [2, 1, 1]])
+    B2 = Matrix([[0.5, 0, 1], [0, 1, 2], [2, 2, 3]])
+    C2 = Matrix([[0, 1, 0], [0, 2, 1], [1, 0, 2]])
+    D2 = Matrix([[2, 2, 0], [1, 1, 1], [3, 2, 1]])
+    H2 = StateSpace(A2, B2, C2, D2)
+    tm3 = H2.rewrite(TransferFunction)
+
+    # outputs for input i obtained at Index i-1. Consider input 1
+    assert tm3[0][0] == TransferFunction(2.0*s**3 + 1.0*s**2 - 10.5*s + 4.5, 1.0*s**3 + 0.5*s**2 - 6.5*s - 2.5, s)
+    assert tm3[0][1] == TransferFunction(2.0*s**3 + 2.0*s**2 - 10.5*s - 3.5, 1.0*s**3 + 0.5*s**2 - 6.5*s - 2.5, s)
+    assert tm3[0][2] == TransferFunction(2.0*s**2 + 5.0*s - 0.5, 1.0*s**3 + 0.5*s**2 - 6.5*s - 2.5, s)
+
+    # TransferFunction to StateSpace
+    SS = TF1.rewrite(StateSpace)
+    assert SS == \
+        StateSpace(Matrix([[     0,          1],
+                           [-wn**2, -2*wn*zeta]]),
+                   Matrix([[0],
+                           [1]]),
+                   Matrix([[1, 0]]),
+                   Matrix([[0]]))
+    assert SS.rewrite(TransferFunction)[0][0] == TF1
+
+    # Transfer function has to be proper
+    raises(ValueError, lambda: TransferFunction(b*s**2 + p**2 - a*p + s, b - p**2, s).rewrite(StateSpace))
+
+
+def test_StateSpace_functions():
+    # https://in.mathworks.com/help/control/ref/statespacemodel.obsv.html
+
+    A_mat = Matrix([[-1.5, -2], [1, 0]])
+    B_mat = Matrix([0.5, 0])
+    C_mat = Matrix([[0, 1]])
+    D_mat = Matrix([1])
+    SS1 = StateSpace(A_mat, B_mat, C_mat, D_mat)
+    SS2 = StateSpace(Matrix([[1, 1], [4, -2]]),Matrix([[0, 1], [0, 2]]),Matrix([[-1, 1], [1, -1]]))
+    SS3 = StateSpace(Matrix([[1, 1], [4, -2]]),Matrix([[1, -1], [1, -1]]))
+
+    # Observability
+    assert SS1.is_observable() == True
+    assert SS2.is_observable() == False
+    assert SS1.observability_matrix() == Matrix([[0, 1], [1, 0]])
+    assert SS2.observability_matrix() == Matrix([[-1,  1], [ 1, -1], [ 3, -3], [-3,  3]])
+    assert SS1.observable_subspace() == [Matrix([[0], [1]]), Matrix([[1], [0]])]
+    assert SS2.observable_subspace() == [Matrix([[-1], [ 1], [ 3], [-3]])]
+
+    # Controllability
+    assert SS1.is_controllable() == True
+    assert SS3.is_controllable() == False
+    assert SS1.controllability_matrix() ==  Matrix([[0.5, -0.75], [  0,   0.5]])
+    assert SS3.controllability_matrix() == Matrix([[1, -1, 2, -2], [1, -1, 2, -2]])
+    assert SS1.controllable_subspace() == [Matrix([[0.5], [  0]]), Matrix([[-0.75], [  0.5]])]
+    assert SS3.controllable_subspace() == [Matrix([[1], [1]])]
+
+    # Append
+    A1 = Matrix([[0, 1], [1, 0]])
+    B1 = Matrix([[0], [1]])
+    C1 = Matrix([[0, 1]])
+    D1 = Matrix([[0]])
+    ss1 = StateSpace(A1, B1, C1, D1)
+    ss2 = StateSpace(Matrix([[1, 0], [0, 1]]), Matrix([[1], [0]]), Matrix([[1, 0]]), Matrix([[1]]))
+    ss3 = ss1.append(ss2)
+
+    assert ss3.num_states == ss1.num_states + ss2.num_states
+    assert ss3.num_inputs == ss1.num_inputs + ss2.num_inputs
+    assert ss3.num_outputs == ss1.num_outputs + ss2.num_outputs
+    assert ss3.state_matrix == Matrix([[0, 1, 0, 0], [1, 0, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]])
+    assert ss3.input_matrix == Matrix([[0, 0], [1, 0], [0, 1], [0, 0]])
+    assert ss3.output_matrix == Matrix([[0, 1, 0, 0], [0, 0, 1, 0]])
+    assert ss3.feedforward_matrix == Matrix([[0, 0], [0, 1]])

lib/python3.12/site-packages/sympy/physics/hep/gamma_matrices.py

@@ -0,0 +1,716 @@
+"""
+    Module to handle gamma matrices expressed as tensor objects.
+
+    Examples
+    ========
+
+    >>> from sympy.physics.hep.gamma_matrices import GammaMatrix as G, LorentzIndex
+    >>> from sympy.tensor.tensor import tensor_indices
+    >>> i = tensor_indices('i', LorentzIndex)
+    >>> G(i)
+    GammaMatrix(i)
+
+    Note that there is already an instance of GammaMatrixHead in four dimensions:
+    GammaMatrix, which is simply declare as
+
+    >>> from sympy.physics.hep.gamma_matrices import GammaMatrix
+    >>> from sympy.tensor.tensor import tensor_indices
+    >>> i = tensor_indices('i', LorentzIndex)
+    >>> GammaMatrix(i)
+    GammaMatrix(i)
+
+    To access the metric tensor
+
+    >>> LorentzIndex.metric
+    metric(LorentzIndex,LorentzIndex)
+
+"""
+from sympy.core.mul import Mul
+from sympy.core.singleton import S
+from sympy.matrices.dense import eye
+from sympy.matrices.expressions.trace import trace
+from sympy.tensor.tensor import TensorIndexType, TensorIndex,\
+    TensMul, TensAdd, tensor_mul, Tensor, TensorHead, TensorSymmetry
+
+
+# DiracSpinorIndex = TensorIndexType('DiracSpinorIndex', dim=4, dummy_name="S")
+
+
+LorentzIndex = TensorIndexType('LorentzIndex', dim=4, dummy_name="L")
+
+
+GammaMatrix = TensorHead("GammaMatrix", [LorentzIndex],
+                         TensorSymmetry.no_symmetry(1), comm=None)
+
+
+def extract_type_tens(expression, component):
+    """
+    Extract from a ``TensExpr`` all tensors with `component`.
+
+    Returns two tensor expressions:
+
+    * the first contains all ``Tensor`` of having `component`.
+    * the second contains all remaining.
+
+
+    """
+    if isinstance(expression, Tensor):
+        sp = [expression]
+    elif isinstance(expression, TensMul):
+        sp = expression.args
+    else:
+        raise ValueError('wrong type')
+
+    # Collect all gamma matrices of the same dimension
+    new_expr = S.One
+    residual_expr = S.One
+    for i in sp:
+        if isinstance(i, Tensor) and i.component == component:
+            new_expr *= i
+        else:
+            residual_expr *= i
+    return new_expr, residual_expr
+
+
+def simplify_gamma_expression(expression):
+    extracted_expr, residual_expr = extract_type_tens(expression, GammaMatrix)
+    res_expr = _simplify_single_line(extracted_expr)
+    return res_expr * residual_expr
+
+
+def simplify_gpgp(ex, sort=True):
+    """
+    simplify products ``G(i)*p(-i)*G(j)*p(-j) -> p(i)*p(-i)``
+
+    Examples
+    ========
+
+    >>> from sympy.physics.hep.gamma_matrices import GammaMatrix as G, \
+        LorentzIndex, simplify_gpgp
+    >>> from sympy.tensor.tensor import tensor_indices, tensor_heads
+    >>> p, q = tensor_heads('p, q', [LorentzIndex])
+    >>> i0,i1,i2,i3,i4,i5 = tensor_indices('i0:6', LorentzIndex)
+    >>> ps = p(i0)*G(-i0)
+    >>> qs = q(i0)*G(-i0)
+    >>> simplify_gpgp(ps*qs*qs)
+    GammaMatrix(-L_0)*p(L_0)*q(L_1)*q(-L_1)
+    """
+    def _simplify_gpgp(ex):
+        components = ex.components
+        a = []
+        comp_map = []
+        for i, comp in enumerate(components):
+            comp_map.extend([i]*comp.rank)
+        dum = [(i[0], i[1], comp_map[i[0]], comp_map[i[1]]) for i in ex.dum]
+        for i in range(len(components)):
+            if components[i] != GammaMatrix:
+                continue
+            for dx in dum:
+                if dx[2] == i:
+                    p_pos1 = dx[3]
+                elif dx[3] == i:
+                    p_pos1 = dx[2]
+                else:
+                    continue
+                comp1 = components[p_pos1]
+                if comp1.comm == 0 and comp1.rank == 1:
+                    a.append((i, p_pos1))
+        if not a:
+            return ex
+        elim = set()
+        tv = []
+        hit = True
+        coeff = S.One
+        ta = None
+        while hit:
+            hit = False
+            for i, ai in enumerate(a[:-1]):
+                if ai[0] in elim:
+                    continue
+                if ai[0] != a[i + 1][0] - 1:
+                    continue
+                if components[ai[1]] != components[a[i + 1][1]]:
+                    continue
+                elim.add(ai[0])
+                elim.add(ai[1])
+                elim.add(a[i + 1][0])
+                elim.add(a[i + 1][1])
+                if not ta:
+                    ta = ex.split()
+                    mu = TensorIndex('mu', LorentzIndex)
+                hit = True
+                if i == 0:
+                    coeff = ex.coeff
+                tx = components[ai[1]](mu)*components[ai[1]](-mu)
+                if len(a) == 2:
+                    tx *= 4  # eye(4)
+                tv.append(tx)
+                break
+
+        if tv:
+            a = [x for j, x in enumerate(ta) if j not in elim]
+            a.extend(tv)
+            t = tensor_mul(*a)*coeff
+            # t = t.replace(lambda x: x.is_Matrix, lambda x: 1)
+            return t
+        else:
+            return ex
+
+    if sort:
+        ex = ex.sorted_components()
+    # this would be better off with pattern matching
+    while 1:
+        t = _simplify_gpgp(ex)
+        if t != ex:
+            ex = t
+        else:
+            return t
+
+
+def gamma_trace(t):
+    """
+    trace of a single line of gamma matrices
+
+    Examples
+    ========
+
+    >>> from sympy.physics.hep.gamma_matrices import GammaMatrix as G, \
+        gamma_trace, LorentzIndex
+    >>> from sympy.tensor.tensor import tensor_indices, tensor_heads
+    >>> p, q = tensor_heads('p, q', [LorentzIndex])
+    >>> i0,i1,i2,i3,i4,i5 = tensor_indices('i0:6', LorentzIndex)
+    >>> ps = p(i0)*G(-i0)
+    >>> qs = q(i0)*G(-i0)
+    >>> gamma_trace(G(i0)*G(i1))
+    4*metric(i0, i1)
+    >>> gamma_trace(ps*ps) - 4*p(i0)*p(-i0)
+    0
+    >>> gamma_trace(ps*qs + ps*ps) - 4*p(i0)*p(-i0) - 4*p(i0)*q(-i0)
+    0
+
+    """
+    if isinstance(t, TensAdd):
+        res = TensAdd(*[gamma_trace(x) for x in t.args])
+        return res
+    t = _simplify_single_line(t)
+    res = _trace_single_line(t)
+    return res
+
+
+def _simplify_single_line(expression):
+    """
+    Simplify single-line product of gamma matrices.
+
+    Examples
+    ========
+
+    >>> from sympy.physics.hep.gamma_matrices import GammaMatrix as G, \
+        LorentzIndex, _simplify_single_line
+    >>> from sympy.tensor.tensor import tensor_indices, TensorHead
+    >>> p = TensorHead('p', [LorentzIndex])
+    >>> i0,i1 = tensor_indices('i0:2', LorentzIndex)
+    >>> _simplify_single_line(G(i0)*G(i1)*p(-i1)*G(-i0)) + 2*G(i0)*p(-i0)
+    0
+
+    """
+    t1, t2 = extract_type_tens(expression, GammaMatrix)
+    if t1 != 1:
+        t1 = kahane_simplify(t1)
+    res = t1*t2
+    return res
+
+
+def _trace_single_line(t):
+    """
+    Evaluate the trace of a single gamma matrix line inside a ``TensExpr``.
+
+    Notes
+    =====
+
+    If there are ``DiracSpinorIndex.auto_left`` and ``DiracSpinorIndex.auto_right``
+    indices trace over them; otherwise traces are not implied (explain)
+
+
+    Examples
+    ========
+
+    >>> from sympy.physics.hep.gamma_matrices import GammaMatrix as G, \
+        LorentzIndex, _trace_single_line
+    >>> from sympy.tensor.tensor import tensor_indices, TensorHead
+    >>> p = TensorHead('p', [LorentzIndex])
+    >>> i0,i1,i2,i3,i4,i5 = tensor_indices('i0:6', LorentzIndex)
+    >>> _trace_single_line(G(i0)*G(i1))
+    4*metric(i0, i1)
+    >>> _trace_single_line(G(i0)*p(-i0)*G(i1)*p(-i1)) - 4*p(i0)*p(-i0)
+    0
+
+    """
+    def _trace_single_line1(t):
+        t = t.sorted_components()
+        components = t.components
+        ncomps = len(components)
+        g = LorentzIndex.metric
+        # gamma matirices are in a[i:j]
+        hit = 0
+        for i in range(ncomps):
+            if components[i] == GammaMatrix:
+                hit = 1
+                break
+
+        for j in range(i + hit, ncomps):
+            if components[j] != GammaMatrix:
+                break
+        else:
+            j = ncomps
+        numG = j - i
+        if numG == 0:
+            tcoeff = t.coeff
+            return t.nocoeff if tcoeff else t
+        if numG % 2 == 1:
+            return TensMul.from_data(S.Zero, [], [], [])
+        elif numG > 4:
+            # find the open matrix indices and connect them:
+            a = t.split()
+            ind1 = a[i].get_indices()[0]
+            ind2 = a[i + 1].get_indices()[0]
+            aa = a[:i] + a[i + 2:]
+            t1 = tensor_mul(*aa)*g(ind1, ind2)
+            t1 = t1.contract_metric(g)
+            args = [t1]
+            sign = 1
+            for k in range(i + 2, j):
+                sign = -sign
+                ind2 = a[k].get_indices()[0]
+                aa = a[:i] + a[i + 1:k] + a[k + 1:]
+                t2 = sign*tensor_mul(*aa)*g(ind1, ind2)
+                t2 = t2.contract_metric(g)
+                t2 = simplify_gpgp(t2, False)
+                args.append(t2)
+            t3 = TensAdd(*args)
+            t3 = _trace_single_line(t3)
+            return t3
+        else:
+            a = t.split()
+            t1 = _gamma_trace1(*a[i:j])
+            a2 = a[:i] + a[j:]
+            t2 = tensor_mul(*a2)
+            t3 = t1*t2
+            if not t3:
+                return t3
+            t3 = t3.contract_metric(g)
+            return t3
+
+    t = t.expand()
+    if isinstance(t, TensAdd):
+        a = [_trace_single_line1(x)*x.coeff for x in t.args]
+        return TensAdd(*a)
+    elif isinstance(t, (Tensor, TensMul)):
+        r = t.coeff*_trace_single_line1(t)
+        return r
+    else:
+        return trace(t)
+
+
+def _gamma_trace1(*a):
+    gctr = 4  # FIXME specific for d=4
+    g = LorentzIndex.metric
+    if not a:
+        return gctr
+    n = len(a)
+    if n%2 == 1:
+        #return TensMul.from_data(S.Zero, [], [], [])
+        return S.Zero
+    if n == 2:
+        ind0 = a[0].get_indices()[0]
+        ind1 = a[1].get_indices()[0]
+        return gctr*g(ind0, ind1)
+    if n == 4:
+        ind0 = a[0].get_indices()[0]
+        ind1 = a[1].get_indices()[0]
+        ind2 = a[2].get_indices()[0]
+        ind3 = a[3].get_indices()[0]
+
+        return gctr*(g(ind0, ind1)*g(ind2, ind3) - \
+           g(ind0, ind2)*g(ind1, ind3) + g(ind0, ind3)*g(ind1, ind2))
+
+
+def kahane_simplify(expression):
+    r"""
+    This function cancels contracted elements in a product of four
+    dimensional gamma matrices, resulting in an expression equal to the given
+    one, without the contracted gamma matrices.
+
+    Parameters
+    ==========
+
+    `expression`    the tensor expression containing the gamma matrices to simplify.
+
+    Notes
+    =====
+
+    If spinor indices are given, the matrices must be given in
+    the order given in the product.
+
+    Algorithm
+    =========
+
+    The idea behind the algorithm is to use some well-known identities,
+    i.e., for contractions enclosing an even number of `\gamma` matrices
+
+    `\gamma^\mu \gamma_{a_1} \cdots \gamma_{a_{2N}} \gamma_\mu = 2 (\gamma_{a_{2N}} \gamma_{a_1} \cdots \gamma_{a_{2N-1}} + \gamma_{a_{2N-1}} \cdots \gamma_{a_1} \gamma_{a_{2N}} )`
+
+    for an odd number of `\gamma` matrices
+
+    `\gamma^\mu \gamma_{a_1} \cdots \gamma_{a_{2N+1}} \gamma_\mu = -2 \gamma_{a_{2N+1}} \gamma_{a_{2N}} \cdots \gamma_{a_{1}}`
+
+    Instead of repeatedly applying these identities to cancel out all contracted indices,
+    it is possible to recognize the links that would result from such an operation,
+    the problem is thus reduced to a simple rearrangement of free gamma matrices.
+
+    Examples
+    ========
+
+    When using, always remember that the original expression coefficient
+    has to be handled separately
+
+    >>> from sympy.physics.hep.gamma_matrices import GammaMatrix as G, LorentzIndex
+    >>> from sympy.physics.hep.gamma_matrices import kahane_simplify
+    >>> from sympy.tensor.tensor import tensor_indices
+    >>> i0, i1, i2 = tensor_indices('i0:3', LorentzIndex)
+    >>> ta = G(i0)*G(-i0)
+    >>> kahane_simplify(ta)
+    Matrix([
+    [4, 0, 0, 0],
+    [0, 4, 0, 0],
+    [0, 0, 4, 0],
+    [0, 0, 0, 4]])
+    >>> tb = G(i0)*G(i1)*G(-i0)
+    >>> kahane_simplify(tb)
+    -2*GammaMatrix(i1)
+    >>> t = G(i0)*G(-i0)
+    >>> kahane_simplify(t)
+    Matrix([
+    [4, 0, 0, 0],
+    [0, 4, 0, 0],
+    [0, 0, 4, 0],
+    [0, 0, 0, 4]])
+    >>> t = G(i0)*G(-i0)
+    >>> kahane_simplify(t)
+    Matrix([
+    [4, 0, 0, 0],
+    [0, 4, 0, 0],
+    [0, 0, 4, 0],
+    [0, 0, 0, 4]])
+
+    If there are no contractions, the same expression is returned
+
+    >>> tc = G(i0)*G(i1)
+    >>> kahane_simplify(tc)
+    GammaMatrix(i0)*GammaMatrix(i1)
+
+    References
+    ==========
+
+    [1] Algorithm for Reducing Contracted Products of gamma Matrices,
+    Joseph Kahane, Journal of Mathematical Physics, Vol. 9, No. 10, October 1968.
+    """
+
+    if isinstance(expression, Mul):
+        return expression
+    if isinstance(expression, TensAdd):
+        return TensAdd(*[kahane_simplify(arg) for arg in expression.args])
+
+    if isinstance(expression, Tensor):
+        return expression
+
+    assert isinstance(expression, TensMul)
+
+    gammas = expression.args
+
+    for gamma in gammas:
+        assert gamma.component == GammaMatrix
+
+    free = expression.free
+    # spinor_free = [_ for _ in expression.free_in_args if _[1] != 0]
+
+    # if len(spinor_free) == 2:
+    #     spinor_free.sort(key=lambda x: x[2])
+    #     assert spinor_free[0][1] == 1 and spinor_free[-1][1] == 2
+    #     assert spinor_free[0][2] == 0
+    # elif spinor_free:
+    #     raise ValueError('spinor indices do not match')
+
+    dum = []
+    for dum_pair in expression.dum:
+        if expression.index_types[dum_pair[0]] == LorentzIndex:
+            dum.append((dum_pair[0], dum_pair[1]))
+
+    dum = sorted(dum)
+
+    if len(dum) == 0:  # or GammaMatrixHead:
+        # no contractions in `expression`, just return it.
+        return expression
+
+    # find the `first_dum_pos`, i.e. the position of the first contracted
+    # gamma matrix, Kahane's algorithm as described in his paper requires the
+    # gamma matrix expression to start with a contracted gamma matrix, this is
+    # a workaround which ignores possible initial free indices, and re-adds
+    # them later.
+
+    first_dum_pos = min(map(min, dum))
+
+    # for p1, p2, a1, a2 in expression.dum_in_args:
+    #     if p1 != 0 or p2 != 0:
+    #         # only Lorentz indices, skip Dirac indices:
+    #         continue
+    #     first_dum_pos = min(p1, p2)
+    #     break
+
+    total_number = len(free) + len(dum)*2
+    number_of_contractions = len(dum)
+
+    free_pos = [None]*total_number
+    for i in free:
+        free_pos[i[1]] = i[0]
+
+    # `index_is_free` is a list of booleans, to identify index position
+    # and whether that index is free or dummy.
+    index_is_free = [False]*total_number
+
+    for i, indx in enumerate(free):
+        index_is_free[indx[1]] = True
+
+    # `links` is a dictionary containing the graph described in Kahane's paper,
+    # to every key correspond one or two values, representing the linked indices.
+    # All values in `links` are integers, negative numbers are used in the case
+    # where it is necessary to insert gamma matrices between free indices, in
+    # order to make Kahane's algorithm work (see paper).
+    links = {i: [] for i in range(first_dum_pos, total_number)}
+
+    # `cum_sign` is a step variable to mark the sign of every index, see paper.
+    cum_sign = -1
+    # `cum_sign_list` keeps storage for all `cum_sign` (every index).
+    cum_sign_list = [None]*total_number
+    block_free_count = 0
+
+    # multiply `resulting_coeff` by the coefficient parameter, the rest
+    # of the algorithm ignores a scalar coefficient.
+    resulting_coeff = S.One
+
+    # initialize a list of lists of indices. The outer list will contain all
+    # additive tensor expressions, while the inner list will contain the
+    # free indices (rearranged according to the algorithm).
+    resulting_indices = [[]]
+
+    # start to count the `connected_components`, which together with the number
+    # of contractions, determines a -1 or +1 factor to be multiplied.
+    connected_components = 1
+
+    # First loop: here we fill `cum_sign_list`, and draw the links
+    # among consecutive indices (they are stored in `links`). Links among
+    # non-consecutive indices will be drawn later.
+    for i, is_free in enumerate(index_is_free):
+        # if `expression` starts with free indices, they are ignored here;
+        # they are later added as they are to the beginning of all
+        # `resulting_indices` list of lists of indices.
+        if i < first_dum_pos:
+            continue
+
+        if is_free:
+            block_free_count += 1
+            # if previous index was free as well, draw an arch in `links`.
+            if block_free_count > 1:
+                links[i - 1].append(i)
+                links[i].append(i - 1)
+        else:
+            # Change the sign of the index (`cum_sign`) if the number of free
+            # indices preceding it is even.
+            cum_sign *= 1 if (block_free_count % 2) else -1
+            if block_free_count == 0 and i != first_dum_pos:
+                # check if there are two consecutive dummy indices:
+                # in this case create virtual indices with negative position,
+                # these "virtual" indices represent the insertion of two
+                # gamma^0 matrices to separate consecutive dummy indices, as
+                # Kahane's algorithm requires dummy indices to be separated by
+                # free indices. The product of two gamma^0 matrices is unity,
+                # so the new expression being examined is the same as the
+                # original one.
+                if cum_sign == -1:
+                    links[-1-i] = [-1-i+1]
+                    links[-1-i+1] = [-1-i]
+            if (i - cum_sign) in links:
+                if i != first_dum_pos:
+                    links[i].append(i - cum_sign)
+                if block_free_count != 0:
+                    if i - cum_sign < len(index_is_free):
+                        if index_is_free[i - cum_sign]:
+                            links[i - cum_sign].append(i)
+            block_free_count = 0
+
+        cum_sign_list[i] = cum_sign
+
+    # The previous loop has only created links between consecutive free indices,
+    # it is necessary to properly create links among dummy (contracted) indices,
+    # according to the rules described in Kahane's paper. There is only one exception
+    # to Kahane's rules: the negative indices, which handle the case of some
+    # consecutive free indices (Kahane's paper just describes dummy indices
+    # separated by free indices, hinting that free indices can be added without
+    # altering the expression result).
+    for i in dum:
+        # get the positions of the two contracted indices:
+        pos1 = i[0]
+        pos2 = i[1]
+
+        # create Kahane's upper links, i.e. the upper arcs between dummy
+        # (i.e. contracted) indices:
+        links[pos1].append(pos2)
+        links[pos2].append(pos1)
+
+        # create Kahane's lower links, this corresponds to the arcs below
+        # the line described in the paper:
+
+        # first we move `pos1` and `pos2` according to the sign of the indices:
+        linkpos1 = pos1 + cum_sign_list[pos1]
+        linkpos2 = pos2 + cum_sign_list[pos2]
+
+        # otherwise, perform some checks before creating the lower arcs:
+
+        # make sure we are not exceeding the total number of indices:
+        if linkpos1 >= total_number:
+            continue
+        if linkpos2 >= total_number:
+            continue
+
+        # make sure we are not below the first dummy index in `expression`:
+        if linkpos1 < first_dum_pos:
+            continue
+        if linkpos2 < first_dum_pos:
+            continue
+
+        # check if the previous loop created "virtual" indices between dummy
+        # indices, in such a case relink `linkpos1` and `linkpos2`:
+        if (-1-linkpos1) in links:
+            linkpos1 = -1-linkpos1
+        if (-1-linkpos2) in links:
+            linkpos2 = -1-linkpos2
+
+        # move only if not next to free index:
+        if linkpos1 >= 0 and not index_is_free[linkpos1]:
+            linkpos1 = pos1
+
+        if linkpos2 >=0 and not index_is_free[linkpos2]:
+            linkpos2 = pos2
+
+        # create the lower arcs:
+        if linkpos2 not in links[linkpos1]:
+            links[linkpos1].append(linkpos2)
+        if linkpos1 not in links[linkpos2]:
+            links[linkpos2].append(linkpos1)
+
+    # This loop starts from the `first_dum_pos` index (first dummy index)
+    # walks through the graph deleting the visited indices from `links`,
+    # it adds a gamma matrix for every free index in encounters, while it
+    # completely ignores dummy indices and virtual indices.
+    pointer = first_dum_pos
+    previous_pointer = 0
+    while True:
+        if pointer in links:
+            next_ones = links.pop(pointer)
+        else:
+            break
+
+        if previous_pointer in next_ones:
+            next_ones.remove(previous_pointer)
+
+        previous_pointer = pointer
+
+        if next_ones:
+            pointer = next_ones[0]
+        else:
+            break
+
+        if pointer == previous_pointer:
+            break
+        if pointer >=0 and free_pos[pointer] is not None:
+            for ri in resulting_indices:
+                ri.append(free_pos[pointer])
+
+    # The following loop removes the remaining connected components in `links`.
+    # If there are free indices inside a connected component, it gives a
+    # contribution to the resulting expression given by the factor
+    # `gamma_a gamma_b ... gamma_z + gamma_z ... gamma_b gamma_a`, in Kahanes's
+    # paper represented as  {gamma_a, gamma_b, ... , gamma_z},
+    # virtual indices are ignored. The variable `connected_components` is
+    # increased by one for every connected component this loop encounters.
+
+    # If the connected component has virtual and dummy indices only
+    # (no free indices), it contributes to `resulting_indices` by a factor of two.
+    # The multiplication by two is a result of the
+    # factor {gamma^0, gamma^0} = 2 I, as it appears in Kahane's paper.
+    # Note: curly brackets are meant as in the paper, as a generalized
+    # multi-element anticommutator!
+
+    while links:
+        connected_components += 1
+        pointer = min(links.keys())
+        previous_pointer = pointer
+        # the inner loop erases the visited indices from `links`, and it adds
+        # all free indices to `prepend_indices` list, virtual indices are
+        # ignored.
+        prepend_indices = []
+        while True:
+            if pointer in links:
+                next_ones = links.pop(pointer)
+            else:
+                break
+
+            if previous_pointer in next_ones:
+                if len(next_ones) > 1:
+                    next_ones.remove(previous_pointer)
+
+            previous_pointer = pointer
+
+            if next_ones:
+                pointer = next_ones[0]
+
+            if pointer >= first_dum_pos and free_pos[pointer] is not None:
+                prepend_indices.insert(0, free_pos[pointer])
+        # if `prepend_indices` is void, it means there are no free indices
+        # in the loop (and it can be shown that there must be a virtual index),
+        # loops of virtual indices only contribute by a factor of two:
+        if len(prepend_indices) == 0:
+            resulting_coeff *= 2
+        # otherwise, add the free indices in `prepend_indices` to
+        # the `resulting_indices`:
+        else:
+            expr1 = prepend_indices
+            expr2 = list(reversed(prepend_indices))
+            resulting_indices = [expri + ri for ri in resulting_indices for expri in (expr1, expr2)]
+
+    # sign correction, as described in Kahane's paper:
+    resulting_coeff *= -1 if (number_of_contractions - connected_components + 1) % 2 else 1
+    # power of two factor, as described in Kahane's paper:
+    resulting_coeff *= 2**(number_of_contractions)
+
+    # If `first_dum_pos` is not zero, it means that there are trailing free gamma
+    # matrices in front of `expression`, so multiply by them:
+    resulting_indices = [ free_pos[0:first_dum_pos] + ri for ri in resulting_indices ]
+
+    resulting_expr = S.Zero
+    for i in resulting_indices:
+        temp_expr = S.One
+        for j in i:
+            temp_expr *= GammaMatrix(j)
+        resulting_expr += temp_expr
+
+    t = resulting_coeff * resulting_expr
+    t1 = None
+    if isinstance(t, TensAdd):
+        t1 = t.args[0]
+    elif isinstance(t, TensMul):
+        t1 = t
+    if t1:
+        pass
+    else:
+        t = eye(4)*t
+    return t

lib/python3.12/site-packages/sympy/physics/hep/tests/test_gamma_matrices.py

@@ -0,0 +1,427 @@
+from sympy.matrices.dense import eye, Matrix
+from sympy.tensor.tensor import tensor_indices, TensorHead, tensor_heads, \
+    TensExpr, canon_bp
+from sympy.physics.hep.gamma_matrices import GammaMatrix as G, LorentzIndex, \
+    kahane_simplify, gamma_trace, _simplify_single_line, simplify_gamma_expression
+from sympy import Symbol
+
+
+def _is_tensor_eq(arg1, arg2):
+    arg1 = canon_bp(arg1)
+    arg2 = canon_bp(arg2)
+    if isinstance(arg1, TensExpr):
+        return arg1.equals(arg2)
+    elif isinstance(arg2, TensExpr):
+        return arg2.equals(arg1)
+    return arg1 == arg2
+
+def execute_gamma_simplify_tests_for_function(tfunc, D):
+    """
+    Perform tests to check if sfunc is able to simplify gamma matrix expressions.
+
+    Parameters
+    ==========
+
+    `sfunc`     a function to simplify a `TIDS`, shall return the simplified `TIDS`.
+    `D`         the number of dimension (in most cases `D=4`).
+
+    """
+
+    mu, nu, rho, sigma = tensor_indices("mu, nu, rho, sigma", LorentzIndex)
+    a1, a2, a3, a4, a5, a6 = tensor_indices("a1:7", LorentzIndex)
+    mu11, mu12, mu21, mu31, mu32, mu41, mu51, mu52 = tensor_indices("mu11, mu12, mu21, mu31, mu32, mu41, mu51, mu52", LorentzIndex)
+    mu61, mu71, mu72 = tensor_indices("mu61, mu71, mu72", LorentzIndex)
+    m0, m1, m2, m3, m4, m5, m6 = tensor_indices("m0:7", LorentzIndex)
+
+    def g(xx, yy):
+        return (G(xx)*G(yy) + G(yy)*G(xx))/2
+
+    # Some examples taken from Kahane's paper, 4 dim only:
+    if D == 4:
+        t = (G(a1)*G(mu11)*G(a2)*G(mu21)*G(-a1)*G(mu31)*G(-a2))
+        assert _is_tensor_eq(tfunc(t), -4*G(mu11)*G(mu31)*G(mu21) - 4*G(mu31)*G(mu11)*G(mu21))
+
+        t = (G(a1)*G(mu11)*G(mu12)*\
+                              G(a2)*G(mu21)*\
+                              G(a3)*G(mu31)*G(mu32)*\
+                              G(a4)*G(mu41)*\
+                              G(-a2)*G(mu51)*G(mu52)*\
+                              G(-a1)*G(mu61)*\
+                              G(-a3)*G(mu71)*G(mu72)*\
+                              G(-a4))
+        assert _is_tensor_eq(tfunc(t), \
+            16*G(mu31)*G(mu32)*G(mu72)*G(mu71)*G(mu11)*G(mu52)*G(mu51)*G(mu12)*G(mu61)*G(mu21)*G(mu41) + 16*G(mu31)*G(mu32)*G(mu72)*G(mu71)*G(mu12)*G(mu51)*G(mu52)*G(mu11)*G(mu61)*G(mu21)*G(mu41) + 16*G(mu71)*G(mu72)*G(mu32)*G(mu31)*G(mu11)*G(mu52)*G(mu51)*G(mu12)*G(mu61)*G(mu21)*G(mu41) + 16*G(mu71)*G(mu72)*G(mu32)*G(mu31)*G(mu12)*G(mu51)*G(mu52)*G(mu11)*G(mu61)*G(mu21)*G(mu41))
+
+    # Fully Lorentz-contracted expressions, these return scalars:
+
+    def add_delta(ne):
+        return ne * eye(4)  # DiracSpinorIndex.delta(DiracSpinorIndex.auto_left, -DiracSpinorIndex.auto_right)
+
+    t = (G(mu)*G(-mu))
+    ts = add_delta(D)
+    assert _is_tensor_eq(tfunc(t), ts)
+
+    t = (G(mu)*G(nu)*G(-mu)*G(-nu))
+    ts = add_delta(2*D - D**2)  # -8
+    assert _is_tensor_eq(tfunc(t), ts)
+
+    t = (G(mu)*G(nu)*G(-nu)*G(-mu))
+    ts = add_delta(D**2)  # 16
+    assert _is_tensor_eq(tfunc(t), ts)
+
+    t = (G(mu)*G(nu)*G(-rho)*G(-nu)*G(-mu)*G(rho))
+    ts = add_delta(4*D - 4*D**2 + D**3)  # 16
+    assert _is_tensor_eq(tfunc(t), ts)
+
+    t = (G(mu)*G(nu)*G(rho)*G(-rho)*G(-nu)*G(-mu))
+    ts = add_delta(D**3)  # 64
+    assert _is_tensor_eq(tfunc(t), ts)
+
+    t = (G(a1)*G(a2)*G(a3)*G(a4)*G(-a3)*G(-a1)*G(-a2)*G(-a4))
+    ts = add_delta(-8*D + 16*D**2 - 8*D**3 + D**4)  # -32
+    assert _is_tensor_eq(tfunc(t), ts)
+
+    t = (G(-mu)*G(-nu)*G(-rho)*G(-sigma)*G(nu)*G(mu)*G(sigma)*G(rho))
+    ts = add_delta(-16*D + 24*D**2 - 8*D**3 + D**4)  # 64
+    assert _is_tensor_eq(tfunc(t), ts)
+
+    t = (G(-mu)*G(nu)*G(-rho)*G(sigma)*G(rho)*G(-nu)*G(mu)*G(-sigma))
+    ts = add_delta(8*D - 12*D**2 + 6*D**3 - D**4)  # -32
+    assert _is_tensor_eq(tfunc(t), ts)
+
+    t = (G(a1)*G(a2)*G(a3)*G(a4)*G(a5)*G(-a3)*G(-a2)*G(-a1)*G(-a5)*G(-a4))
+    ts = add_delta(64*D - 112*D**2 + 60*D**3 - 12*D**4 + D**5)  # 256
+    assert _is_tensor_eq(tfunc(t), ts)
+
+    t = (G(a1)*G(a2)*G(a3)*G(a4)*G(a5)*G(-a3)*G(-a1)*G(-a2)*G(-a4)*G(-a5))
+    ts = add_delta(64*D - 120*D**2 + 72*D**3 - 16*D**4 + D**5)  # -128
+    assert _is_tensor_eq(tfunc(t), ts)
+
+    t = (G(a1)*G(a2)*G(a3)*G(a4)*G(a5)*G(a6)*G(-a3)*G(-a2)*G(-a1)*G(-a6)*G(-a5)*G(-a4))
+    ts = add_delta(416*D - 816*D**2 + 528*D**3 - 144*D**4 + 18*D**5 - D**6)  # -128
+    assert _is_tensor_eq(tfunc(t), ts)
+
+    t = (G(a1)*G(a2)*G(a3)*G(a4)*G(a5)*G(a6)*G(-a2)*G(-a3)*G(-a1)*G(-a6)*G(-a4)*G(-a5))
+    ts = add_delta(416*D - 848*D**2 + 584*D**3 - 172*D**4 + 22*D**5 - D**6)  # -128
+    assert _is_tensor_eq(tfunc(t), ts)
+
+    # Expressions with free indices:
+
+    t = (G(mu)*G(nu)*G(rho)*G(sigma)*G(-mu))
+    assert _is_tensor_eq(tfunc(t), (-2*G(sigma)*G(rho)*G(nu) + (4-D)*G(nu)*G(rho)*G(sigma)))
+
+    t = (G(mu)*G(nu)*G(-mu))
+    assert _is_tensor_eq(tfunc(t), (2-D)*G(nu))
+
+    t = (G(mu)*G(nu)*G(rho)*G(-mu))
+    assert _is_tensor_eq(tfunc(t), 2*G(nu)*G(rho) + 2*G(rho)*G(nu) - (4-D)*G(nu)*G(rho))
+
+    t = 2*G(m2)*G(m0)*G(m1)*G(-m0)*G(-m1)
+    st = tfunc(t)
+    assert _is_tensor_eq(st, (D*(-2*D + 4))*G(m2))
+
+    t = G(m2)*G(m0)*G(m1)*G(-m0)*G(-m2)
+    st = tfunc(t)
+    assert _is_tensor_eq(st, ((-D + 2)**2)*G(m1))
+
+    t = G(m0)*G(m1)*G(m2)*G(m3)*G(-m1)
+    st = tfunc(t)
+    assert _is_tensor_eq(st, (D - 4)*G(m0)*G(m2)*G(m3) + 4*G(m0)*g(m2, m3))
+
+    t = G(m0)*G(m1)*G(m2)*G(m3)*G(-m1)*G(-m0)
+    st = tfunc(t)
+    assert _is_tensor_eq(st, ((D - 4)**2)*G(m2)*G(m3) + (8*D - 16)*g(m2, m3))
+
+    t = G(m2)*G(m0)*G(m1)*G(-m2)*G(-m0)
+    st = tfunc(t)
+    assert _is_tensor_eq(st, ((-D + 2)*(D - 4) + 4)*G(m1))
+
+    t = G(m3)*G(m1)*G(m0)*G(m2)*G(-m3)*G(-m0)*G(-m2)
+    st = tfunc(t)
+    assert _is_tensor_eq(st, (-4*D + (-D + 2)**2*(D - 4) + 8)*G(m1))
+
+    t = 2*G(m0)*G(m1)*G(m2)*G(m3)*G(-m0)
+    st = tfunc(t)
+    assert _is_tensor_eq(st, ((-2*D + 8)*G(m1)*G(m2)*G(m3) - 4*G(m3)*G(m2)*G(m1)))
+
+    t = G(m5)*G(m0)*G(m1)*G(m4)*G(m2)*G(-m4)*G(m3)*G(-m0)
+    st = tfunc(t)
+    assert _is_tensor_eq(st, (((-D + 2)*(-D + 4))*G(m5)*G(m1)*G(m2)*G(m3) + (2*D - 4)*G(m5)*G(m3)*G(m2)*G(m1)))
+
+    t = -G(m0)*G(m1)*G(m2)*G(m3)*G(-m0)*G(m4)
+    st = tfunc(t)
+    assert _is_tensor_eq(st, ((D - 4)*G(m1)*G(m2)*G(m3)*G(m4) + 2*G(m3)*G(m2)*G(m1)*G(m4)))
+
+    t = G(-m5)*G(m0)*G(m1)*G(m2)*G(m3)*G(m4)*G(-m0)*G(m5)
+    st = tfunc(t)
+
+    result1 = ((-D + 4)**2 + 4)*G(m1)*G(m2)*G(m3)*G(m4) +\
+        (4*D - 16)*G(m3)*G(m2)*G(m1)*G(m4) + (4*D - 16)*G(m4)*G(m1)*G(m2)*G(m3)\
+        + 4*G(m2)*G(m1)*G(m4)*G(m3) + 4*G(m3)*G(m4)*G(m1)*G(m2) +\
+        4*G(m4)*G(m3)*G(m2)*G(m1)
+
+    # Kahane's algorithm yields this result, which is equivalent to `result1`
+    # in four dimensions, but is not automatically recognized as equal:
+    result2 = 8*G(m1)*G(m2)*G(m3)*G(m4) + 8*G(m4)*G(m3)*G(m2)*G(m1)
+
+    if D == 4:
+        assert _is_tensor_eq(st, (result1)) or _is_tensor_eq(st, (result2))
+    else:
+        assert _is_tensor_eq(st, (result1))
+
+    # and a few very simple cases, with no contracted indices:
+
+    t = G(m0)
+    st = tfunc(t)
+    assert _is_tensor_eq(st, t)
+
+    t = -7*G(m0)
+    st = tfunc(t)
+    assert _is_tensor_eq(st, t)
+
+    t = 224*G(m0)*G(m1)*G(-m2)*G(m3)
+    st = tfunc(t)
+    assert _is_tensor_eq(st, t)
+
+
+def test_kahane_algorithm():
+    # Wrap this function to convert to and from TIDS:
+
+    def tfunc(e):
+        return _simplify_single_line(e)
+
+    execute_gamma_simplify_tests_for_function(tfunc, D=4)
+
+
+def test_kahane_simplify1():
+    i0,i1,i2,i3,i4,i5,i6,i7,i8,i9,i10,i11,i12,i13,i14,i15 = tensor_indices('i0:16', LorentzIndex)
+    mu, nu, rho, sigma = tensor_indices("mu, nu, rho, sigma", LorentzIndex)
+    D = 4
+    t = G(i0)*G(i1)
+    r = kahane_simplify(t)
+    assert r.equals(t)
+
+    t = G(i0)*G(i1)*G(-i0)
+    r = kahane_simplify(t)
+    assert r.equals(-2*G(i1))
+    t = G(i0)*G(i1)*G(-i0)
+    r = kahane_simplify(t)
+    assert r.equals(-2*G(i1))
+
+    t = G(i0)*G(i1)
+    r = kahane_simplify(t)
+    assert r.equals(t)
+    t = G(i0)*G(i1)
+    r = kahane_simplify(t)
+    assert r.equals(t)
+    t = G(i0)*G(-i0)
+    r = kahane_simplify(t)
+    assert r.equals(4*eye(4))
+    t = G(i0)*G(-i0)
+    r = kahane_simplify(t)
+    assert r.equals(4*eye(4))
+    t = G(i0)*G(-i0)
+    r = kahane_simplify(t)
+    assert r.equals(4*eye(4))
+    t = G(i0)*G(i1)*G(-i0)
+    r = kahane_simplify(t)
+    assert r.equals(-2*G(i1))
+    t = G(i0)*G(i1)*G(-i0)*G(-i1)
+    r = kahane_simplify(t)
+    assert r.equals((2*D - D**2)*eye(4))
+    t = G(i0)*G(i1)*G(-i0)*G(-i1)
+    r = kahane_simplify(t)
+    assert r.equals((2*D - D**2)*eye(4))
+    t = G(i0)*G(-i0)*G(i1)*G(-i1)
+    r = kahane_simplify(t)
+    assert r.equals(16*eye(4))
+    t = (G(mu)*G(nu)*G(-nu)*G(-mu))
+    r = kahane_simplify(t)
+    assert r.equals(D**2*eye(4))
+    t = (G(mu)*G(nu)*G(-nu)*G(-mu))
+    r = kahane_simplify(t)
+    assert r.equals(D**2*eye(4))
+    t = (G(mu)*G(nu)*G(-nu)*G(-mu))
+    r = kahane_simplify(t)
+    assert r.equals(D**2*eye(4))
+    t = (G(mu)*G(nu)*G(-rho)*G(-nu)*G(-mu)*G(rho))
+    r = kahane_simplify(t)
+    assert r.equals((4*D - 4*D**2 + D**3)*eye(4))
+    t = (G(-mu)*G(-nu)*G(-rho)*G(-sigma)*G(nu)*G(mu)*G(sigma)*G(rho))
+    r = kahane_simplify(t)
+    assert r.equals((-16*D + 24*D**2 - 8*D**3 + D**4)*eye(4))
+    t = (G(-mu)*G(nu)*G(-rho)*G(sigma)*G(rho)*G(-nu)*G(mu)*G(-sigma))
+    r = kahane_simplify(t)
+    assert r.equals((8*D - 12*D**2 + 6*D**3 - D**4)*eye(4))
+
+    # Expressions with free indices:
+    t = (G(mu)*G(nu)*G(rho)*G(sigma)*G(-mu))
+    r = kahane_simplify(t)
+    assert r.equals(-2*G(sigma)*G(rho)*G(nu))
+    t = (G(mu)*G(-mu)*G(rho)*G(sigma))
+    r = kahane_simplify(t)
+    assert r.equals(4*G(rho)*G(sigma))
+    t = (G(rho)*G(sigma)*G(mu)*G(-mu))
+    r = kahane_simplify(t)
+    assert r.equals(4*G(rho)*G(sigma))
+
+def test_gamma_matrix_class():
+    i, j, k = tensor_indices('i,j,k', LorentzIndex)
+
+    # define another type of TensorHead to see if exprs are correctly handled:
+    A = TensorHead('A', [LorentzIndex])
+
+    t = A(k)*G(i)*G(-i)
+    ts = simplify_gamma_expression(t)
+    assert _is_tensor_eq(ts, Matrix([
+        [4, 0, 0, 0],
+        [0, 4, 0, 0],
+        [0, 0, 4, 0],
+        [0, 0, 0, 4]])*A(k))
+
+    t = G(i)*A(k)*G(j)
+    ts = simplify_gamma_expression(t)
+    assert _is_tensor_eq(ts, A(k)*G(i)*G(j))
+
+    execute_gamma_simplify_tests_for_function(simplify_gamma_expression, D=4)
+
+
+def test_gamma_matrix_trace():
+    g = LorentzIndex.metric
+
+    m0, m1, m2, m3, m4, m5, m6 = tensor_indices('m0:7', LorentzIndex)
+    n0, n1, n2, n3, n4, n5 = tensor_indices('n0:6', LorentzIndex)
+
+    # working in D=4 dimensions
+    D = 4
+
+    # traces of odd number of gamma matrices are zero:
+    t = G(m0)
+    t1 = gamma_trace(t)
+    assert t1.equals(0)
+
+    t = G(m0)*G(m1)*G(m2)
+    t1 = gamma_trace(t)
+    assert t1.equals(0)
+
+    t = G(m0)*G(m1)*G(-m0)
+    t1 = gamma_trace(t)
+    assert t1.equals(0)
+
+    t = G(m0)*G(m1)*G(m2)*G(m3)*G(m4)
+    t1 = gamma_trace(t)
+    assert t1.equals(0)
+
+    # traces without internal contractions:
+    t = G(m0)*G(m1)
+    t1 = gamma_trace(t)
+    assert _is_tensor_eq(t1, 4*g(m0, m1))
+
+    t = G(m0)*G(m1)*G(m2)*G(m3)
+    t1 = gamma_trace(t)
+    t2 = -4*g(m0, m2)*g(m1, m3) + 4*g(m0, m1)*g(m2, m3) + 4*g(m0, m3)*g(m1, m2)
+    assert _is_tensor_eq(t1, t2)
+
+    t = G(m0)*G(m1)*G(m2)*G(m3)*G(m4)*G(m5)
+    t1 = gamma_trace(t)
+    t2 = t1*g(-m0, -m5)
+    t2 = t2.contract_metric(g)
+    assert _is_tensor_eq(t2, D*gamma_trace(G(m1)*G(m2)*G(m3)*G(m4)))
+
+    # traces of expressions with internal contractions:
+    t = G(m0)*G(-m0)
+    t1 = gamma_trace(t)
+    assert t1.equals(4*D)
+
+    t = G(m0)*G(m1)*G(-m0)*G(-m1)
+    t1 = gamma_trace(t)
+    assert t1.equals(8*D - 4*D**2)
+
+    t = G(m0)*G(m1)*G(m2)*G(m3)*G(m4)*G(-m0)
+    t1 = gamma_trace(t)
+    t2 = (-4*D)*g(m1, m3)*g(m2, m4) + (4*D)*g(m1, m2)*g(m3, m4) + \
+                 (4*D)*g(m1, m4)*g(m2, m3)
+    assert _is_tensor_eq(t1, t2)
+
+    t = G(-m5)*G(m0)*G(m1)*G(m2)*G(m3)*G(m4)*G(-m0)*G(m5)
+    t1 = gamma_trace(t)
+    t2 = (32*D + 4*(-D + 4)**2 - 64)*(g(m1, m2)*g(m3, m4) - \
+            g(m1, m3)*g(m2, m4) + g(m1, m4)*g(m2, m3))
+    assert _is_tensor_eq(t1, t2)
+
+    t = G(m0)*G(m1)*G(-m0)*G(m3)
+    t1 = gamma_trace(t)
+    assert t1.equals((-4*D + 8)*g(m1, m3))
+
+#    p, q = S1('p,q')
+#    ps = p(m0)*G(-m0)
+#    qs = q(m0)*G(-m0)
+#    t = ps*qs*ps*qs
+#    t1 = gamma_trace(t)
+#    assert t1 == 8*p(m0)*q(-m0)*p(m1)*q(-m1) - 4*p(m0)*p(-m0)*q(m1)*q(-m1)
+
+    t = G(m0)*G(m1)*G(m2)*G(m3)*G(m4)*G(m5)*G(-m0)*G(-m1)*G(-m2)*G(-m3)*G(-m4)*G(-m5)
+    t1 = gamma_trace(t)
+    assert t1.equals(-4*D**6 + 120*D**5 - 1040*D**4 + 3360*D**3 - 4480*D**2 + 2048*D)
+
+    t = G(m0)*G(m1)*G(n1)*G(m2)*G(n2)*G(m3)*G(m4)*G(-n2)*G(-n1)*G(-m0)*G(-m1)*G(-m2)*G(-m3)*G(-m4)
+    t1 = gamma_trace(t)
+    tresu = -7168*D + 16768*D**2 - 14400*D**3 + 5920*D**4 - 1232*D**5 + 120*D**6 - 4*D**7
+    assert t1.equals(tresu)
+
+    # checked with Mathematica
+    # In[1]:= <<Tracer.m
+    # In[2]:= Spur[l];
+    # In[3]:= GammaTrace[l, {m0},{m1},{n1},{m2},{n2},{m3},{m4},{n3},{n4},{m0},{m1},{m2},{m3},{m4}]
+    t = G(m0)*G(m1)*G(n1)*G(m2)*G(n2)*G(m3)*G(m4)*G(n3)*G(n4)*G(-m0)*G(-m1)*G(-m2)*G(-m3)*G(-m4)
+    t1 = gamma_trace(t)
+#    t1 = t1.expand_coeff()
+    c1 = -4*D**5 + 120*D**4 - 1200*D**3 + 5280*D**2 - 10560*D + 7808
+    c2 = -4*D**5 + 88*D**4 - 560*D**3 + 1440*D**2 - 1600*D + 640
+    assert _is_tensor_eq(t1, c1*g(n1, n4)*g(n2, n3) + c2*g(n1, n2)*g(n3, n4) + \
+            (-c1)*g(n1, n3)*g(n2, n4))
+
+    p, q = tensor_heads('p,q', [LorentzIndex])
+    ps = p(m0)*G(-m0)
+    qs = q(m0)*G(-m0)
+    p2 = p(m0)*p(-m0)
+    q2 = q(m0)*q(-m0)
+    pq = p(m0)*q(-m0)
+    t = ps*qs*ps*qs
+    r = gamma_trace(t)
+    assert _is_tensor_eq(r, 8*pq*pq - 4*p2*q2)
+    t = ps*qs*ps*qs*ps*qs
+    r = gamma_trace(t)
+    assert _is_tensor_eq(r, -12*p2*pq*q2 + 16*pq*pq*pq)
+    t = ps*qs*ps*qs*ps*qs*ps*qs
+    r = gamma_trace(t)
+    assert _is_tensor_eq(r, -32*pq*pq*p2*q2 + 32*pq*pq*pq*pq + 4*p2*p2*q2*q2)
+
+    t = 4*p(m1)*p(m0)*p(-m0)*q(-m1)*q(m2)*q(-m2)
+    assert _is_tensor_eq(gamma_trace(t), t)
+    t = ps*ps*ps*ps*ps*ps*ps*ps
+    r = gamma_trace(t)
+    assert r.equals(4*p2*p2*p2*p2)
+
+
+def test_bug_13636():
+    """Test issue 13636 regarding handling traces of sums of products
+    of GammaMatrix mixed with other factors."""
+    pi, ki, pf = tensor_heads("pi, ki, pf", [LorentzIndex])
+    i0, i1, i2, i3, i4 = tensor_indices("i0:5", LorentzIndex)
+    x = Symbol("x")
+    pis = pi(i2) * G(-i2)
+    kis = ki(i3) * G(-i3)
+    pfs = pf(i4) * G(-i4)
+
+    a = pfs * G(i0) * kis * G(i1) * pis * G(-i1) * kis * G(-i0)
+    b = pfs * G(i0) * kis * G(i1) * pis * x * G(-i0) * pi(-i1)
+    ta = gamma_trace(a)
+    tb = gamma_trace(b)
+    t_a_plus_b = gamma_trace(a + b)
+    assert ta == 4 * (
+        -4 * ki(i0) * ki(-i0) * pf(i1) * pi(-i1)
+        + 8 * ki(i0) * ki(i1) * pf(-i0) * pi(-i1)
+    )
+    assert tb == -8 * x * ki(i0) * pf(-i0) * pi(i1) * pi(-i1)
+    assert t_a_plus_b == ta + tb

lib/python3.12/site-packages/sympy/physics/mechanics/__init__.py

@@ -0,0 +1,90 @@
+__all__ = [
+    'vector',
+
+    'CoordinateSym', 'ReferenceFrame', 'Dyadic', 'Vector', 'Point', 'cross',
+    'dot', 'express', 'time_derivative', 'outer', 'kinematic_equations',
+    'get_motion_params', 'partial_velocity', 'dynamicsymbols', 'vprint',
+    'vsstrrepr', 'vsprint', 'vpprint', 'vlatex', 'init_vprinting', 'curl',
+    'divergence', 'gradient', 'is_conservative', 'is_solenoidal',
+    'scalar_potential', 'scalar_potential_difference',
+
+    'KanesMethod',
+
+    'RigidBody',
+
+    'linear_momentum', 'angular_momentum', 'kinetic_energy', 'potential_energy',
+    'Lagrangian', 'mechanics_printing', 'mprint', 'msprint', 'mpprint',
+    'mlatex', 'msubs', 'find_dynamicsymbols',
+
+    'inertia', 'inertia_of_point_mass', 'Inertia',
+
+    'Force', 'Torque',
+
+    'Particle',
+
+    'LagrangesMethod',
+
+    'Linearizer',
+
+    'Body',
+
+    'SymbolicSystem', 'System',
+
+    'PinJoint', 'PrismaticJoint', 'CylindricalJoint', 'PlanarJoint',
+    'SphericalJoint', 'WeldJoint',
+
+    'JointsMethod',
+
+    'WrappingCylinder', 'WrappingGeometryBase', 'WrappingSphere',
+
+    'PathwayBase', 'LinearPathway', 'ObstacleSetPathway', 'WrappingPathway',
+
+    'ActuatorBase', 'ForceActuator', 'LinearDamper', 'LinearSpring',
+    'TorqueActuator', 'DuffingSpring'
+]
+
+from sympy.physics import vector
+
+from sympy.physics.vector import (CoordinateSym, ReferenceFrame, Dyadic, Vector, Point,
+        cross, dot, express, time_derivative, outer, kinematic_equations,
+        get_motion_params, partial_velocity, dynamicsymbols, vprint,
+        vsstrrepr, vsprint, vpprint, vlatex, init_vprinting, curl, divergence,
+        gradient, is_conservative, is_solenoidal, scalar_potential,
+        scalar_potential_difference)
+
+from .kane import KanesMethod
+
+from .rigidbody import RigidBody
+
+from .functions import (linear_momentum, angular_momentum, kinetic_energy,
+                        potential_energy, Lagrangian, mechanics_printing,
+                        mprint, msprint, mpprint, mlatex, msubs,
+                        find_dynamicsymbols)
+
+from .inertia import inertia, inertia_of_point_mass, Inertia
+
+from .loads import Force, Torque
+
+from .particle import Particle
+
+from .lagrange import LagrangesMethod
+
+from .linearize import Linearizer
+
+from .body import Body
+
+from .system import SymbolicSystem, System
+
+from .jointsmethod import JointsMethod
+
+from .joint import (PinJoint, PrismaticJoint, CylindricalJoint, PlanarJoint,
+                    SphericalJoint, WeldJoint)
+
+from .wrapping_geometry import (WrappingCylinder, WrappingGeometryBase,
+                                WrappingSphere)
+
+from .pathway import (PathwayBase, LinearPathway, ObstacleSetPathway,
+                      WrappingPathway)
+
+from .actuator import (ActuatorBase, ForceActuator, LinearDamper, LinearSpring,
+                       TorqueActuator, DuffingSpring)

lib/python3.12/site-packages/sympy/physics/mechanics/actuator.py

@@ -0,0 +1,992 @@
+"""Implementations of actuators for linked force and torque application."""
+
+from abc import ABC, abstractmethod
+
+from sympy import S, sympify
+from sympy.physics.mechanics.joint import PinJoint
+from sympy.physics.mechanics.loads import Torque
+from sympy.physics.mechanics.pathway import PathwayBase
+from sympy.physics.mechanics.rigidbody import RigidBody
+from sympy.physics.vector import ReferenceFrame, Vector
+
+
+__all__ = [
+    'ActuatorBase',
+    'ForceActuator',
+    'LinearDamper',
+    'LinearSpring',
+    'TorqueActuator',
+    'DuffingSpring'
+]
+
+
+class ActuatorBase(ABC):
+    """Abstract base class for all actuator classes to inherit from.
+
+    Notes
+    =====
+
+    Instances of this class cannot be directly instantiated by users. However,
+    it can be used to created custom actuator types through subclassing.
+
+    """
+
+    def __init__(self):
+        """Initializer for ``ActuatorBase``."""
+        pass
+
+    @abstractmethod
+    def to_loads(self):
+        """Loads required by the equations of motion method classes.
+
+        Explanation
+        ===========
+
+        ``KanesMethod`` requires a list of ``Point``-``Vector`` tuples to be
+        passed to the ``loads`` parameters of its ``kanes_equations`` method
+        when constructing the equations of motion. This method acts as a
+        utility to produce the correctly-structred pairs of points and vectors
+        required so that these can be easily concatenated with other items in
+        the list of loads and passed to ``KanesMethod.kanes_equations``. These
+        loads are also in the correct form to also be passed to the other
+        equations of motion method classes, e.g. ``LagrangesMethod``.
+
+        """
+        pass
+
+    def __repr__(self):
+        """Default representation of an actuator."""
+        return f'{self.__class__.__name__}()'
+
+
+class ForceActuator(ActuatorBase):
+    """Force-producing actuator.
+
+    Explanation
+    ===========
+
+    A ``ForceActuator`` is an actuator that produces a (expansile) force along
+    its length.
+
+    A force actuator uses a pathway instance to determine the direction and
+    number of forces that it applies to a system. Consider the simplest case
+    where a ``LinearPathway`` instance is used. This pathway is made up of two
+    points that can move relative to each other, and results in a pair of equal
+    and opposite forces acting on the endpoints. If the positive time-varying
+    Euclidean distance between the two points is defined, then the "extension
+    velocity" is the time derivative of this distance. The extension velocity
+    is positive when the two points are moving away from each other and
+    negative when moving closer to each other. The direction for the force
+    acting on either point is determined by constructing a unit vector directed
+    from the other point to this point. This establishes a sign convention such
+    that a positive force magnitude tends to push the points apart, this is the
+    meaning of "expansile" in this context. The following diagram shows the
+    positive force sense and the distance between the points::
+
+       P           Q
+       o<--- F --->o
+       |           |
+       |<--l(t)--->|
+
+    Examples
+    ========
+
+    To construct an actuator, an expression (or symbol) must be supplied to
+    represent the force it can produce, alongside a pathway specifying its line
+    of action. Let's also create a global reference frame and spatially fix one
+    of the points in it while setting the other to be positioned such that it
+    can freely move in the frame's x direction specified by the coordinate
+    ``q``.
+
+    >>> from sympy import symbols
+    >>> from sympy.physics.mechanics import (ForceActuator, LinearPathway,
+    ...     Point, ReferenceFrame)
+    >>> from sympy.physics.vector import dynamicsymbols
+    >>> N = ReferenceFrame('N')
+    >>> q = dynamicsymbols('q')
+    >>> force = symbols('F')
+    >>> pA, pB = Point('pA'), Point('pB')
+    >>> pA.set_vel(N, 0)
+    >>> pB.set_pos(pA, q*N.x)
+    >>> pB.pos_from(pA)
+    q(t)*N.x
+    >>> linear_pathway = LinearPathway(pA, pB)
+    >>> actuator = ForceActuator(force, linear_pathway)
+    >>> actuator
+    ForceActuator(F, LinearPathway(pA, pB))
+
+    Parameters
+    ==========
+
+    force : Expr
+        The scalar expression defining the (expansile) force that the actuator
+        produces.
+    pathway : PathwayBase
+        The pathway that the actuator follows. This must be an instance of a
+        concrete subclass of ``PathwayBase``, e.g. ``LinearPathway``.
+
+    """
+
+    def __init__(self, force, pathway):
+        """Initializer for ``ForceActuator``.
+
+        Parameters
+        ==========
+
+        force : Expr
+            The scalar expression defining the (expansile) force that the
+            actuator produces.
+        pathway : PathwayBase
+            The pathway that the actuator follows. This must be an instance of
+            a concrete subclass of ``PathwayBase``, e.g. ``LinearPathway``.
+
+        """
+        self.force = force
+        self.pathway = pathway
+
+    @property
+    def force(self):
+        """The magnitude of the force produced by the actuator."""
+        return self._force
+
+    @force.setter
+    def force(self, force):
+        if hasattr(self, '_force'):
+            msg = (
+                f'Can\'t set attribute `force` to {repr(force)} as it is '
+                f'immutable.'
+            )
+            raise AttributeError(msg)
+        self._force = sympify(force, strict=True)
+
+    @property
+    def pathway(self):
+        """The ``Pathway`` defining the actuator's line of action."""
+        return self._pathway
+
+    @pathway.setter
+    def pathway(self, pathway):
+        if hasattr(self, '_pathway'):
+            msg = (
+                f'Can\'t set attribute `pathway` to {repr(pathway)} as it is '
+                f'immutable.'
+            )
+            raise AttributeError(msg)
+        if not isinstance(pathway, PathwayBase):
+            msg = (
+                f'Value {repr(pathway)} passed to `pathway` was of type '
+                f'{type(pathway)}, must be {PathwayBase}.'
+            )
+            raise TypeError(msg)
+        self._pathway = pathway
+
+    def to_loads(self):
+        """Loads required by the equations of motion method classes.
+
+        Explanation
+        ===========
+
+        ``KanesMethod`` requires a list of ``Point``-``Vector`` tuples to be
+        passed to the ``loads`` parameters of its ``kanes_equations`` method
+        when constructing the equations of motion. This method acts as a
+        utility to produce the correctly-structred pairs of points and vectors
+        required so that these can be easily concatenated with other items in
+        the list of loads and passed to ``KanesMethod.kanes_equations``. These
+        loads are also in the correct form to also be passed to the other
+        equations of motion method classes, e.g. ``LagrangesMethod``.
+
+        Examples
+        ========
+
+        The below example shows how to generate the loads produced by a force
+        actuator that follows a linear pathway. In this example we'll assume
+        that the force actuator is being used to model a simple linear spring.
+        First, create a linear pathway between two points separated by the
+        coordinate ``q`` in the ``x`` direction of the global frame ``N``.
+
+        >>> from sympy.physics.mechanics import (LinearPathway, Point,
+        ...     ReferenceFrame)
+        >>> from sympy.physics.vector import dynamicsymbols
+        >>> q = dynamicsymbols('q')
+        >>> N = ReferenceFrame('N')
+        >>> pA, pB = Point('pA'), Point('pB')
+        >>> pB.set_pos(pA, q*N.x)
+        >>> pathway = LinearPathway(pA, pB)
+
+        Now create a symbol ``k`` to describe the spring's stiffness and
+        instantiate a force actuator that produces a (contractile) force
+        proportional to both the spring's stiffness and the pathway's length.
+        Note that actuator classes use the sign convention that expansile
+        forces are positive, so for a spring to produce a contractile force the
+        spring force needs to be calculated as the negative for the stiffness
+        multiplied by the length.
+
+        >>> from sympy import symbols
+        >>> from sympy.physics.mechanics import ForceActuator
+        >>> stiffness = symbols('k')
+        >>> spring_force = -stiffness*pathway.length
+        >>> spring = ForceActuator(spring_force, pathway)
+
+        The forces produced by the spring can be generated in the list of loads
+        form that ``KanesMethod`` (and other equations of motion methods)
+        requires by calling the ``to_loads`` method.
+
+        >>> spring.to_loads()
+        [(pA, k*q(t)*N.x), (pB, - k*q(t)*N.x)]
+
+        A simple linear damper can be modeled in a similar way. Create another
+        symbol ``c`` to describe the dampers damping coefficient. This time
+        instantiate a force actuator that produces a force proportional to both
+        the damper's damping coefficient and the pathway's extension velocity.
+        Note that the damping force is negative as it acts in the opposite
+        direction to which the damper is changing in length.
+
+        >>> damping_coefficient = symbols('c')
+        >>> damping_force = -damping_coefficient*pathway.extension_velocity
+        >>> damper = ForceActuator(damping_force, pathway)
+
+        Again, the forces produces by the damper can be generated by calling
+        the ``to_loads`` method.
+
+        >>> damper.to_loads()
+        [(pA, c*Derivative(q(t), t)*N.x), (pB, - c*Derivative(q(t), t)*N.x)]
+
+        """
+        return self.pathway.to_loads(self.force)
+
+    def __repr__(self):
+        """Representation of a ``ForceActuator``."""
+        return f'{self.__class__.__name__}({self.force}, {self.pathway})'
+
+
+class LinearSpring(ForceActuator):
+    """A spring with its spring force as a linear function of its length.
+
+    Explanation
+    ===========
+
+    Note that the "linear" in the name ``LinearSpring`` refers to the fact that
+    the spring force is a linear function of the springs length. I.e. for a
+    linear spring with stiffness ``k``, distance between its ends of ``x``, and
+    an equilibrium length of ``0``, the spring force will be ``-k*x``, which is
+    a linear function in ``x``. To create a spring that follows a linear, or
+    straight, pathway between its two ends, a ``LinearPathway`` instance needs
+    to be passed to the ``pathway`` parameter.
+
+    A ``LinearSpring`` is a subclass of ``ForceActuator`` and so follows the
+    same sign conventions for length, extension velocity, and the direction of
+    the forces it applies to its points of attachment on bodies. The sign
+    convention for the direction of forces is such that, for the case where a
+    linear spring is instantiated with a ``LinearPathway`` instance as its
+    pathway, they act to push the two ends of the spring away from one another.
+    Because springs produces a contractile force and acts to pull the two ends
+    together towards the equilibrium length when stretched, the scalar portion
+    of the forces on the endpoint are negative in order to flip the sign of the
+    forces on the endpoints when converted into vector quantities. The
+    following diagram shows the positive force sense and the distance between
+    the points::
+
+       P           Q
+       o<--- F --->o
+       |           |
+       |<--l(t)--->|
+
+    Examples
+    ========
+
+    To construct a linear spring, an expression (or symbol) must be supplied to
+    represent the stiffness (spring constant) of the spring, alongside a
+    pathway specifying its line of action. Let's also create a global reference
+    frame and spatially fix one of the points in it while setting the other to
+    be positioned such that it can freely move in the frame's x direction
+    specified by the coordinate ``q``.
+
+    >>> from sympy import symbols
+    >>> from sympy.physics.mechanics import (LinearPathway, LinearSpring,
+    ...     Point, ReferenceFrame)
+    >>> from sympy.physics.vector import dynamicsymbols
+    >>> N = ReferenceFrame('N')
+    >>> q = dynamicsymbols('q')
+    >>> stiffness = symbols('k')
+    >>> pA, pB = Point('pA'), Point('pB')
+    >>> pA.set_vel(N, 0)
+    >>> pB.set_pos(pA, q*N.x)
+    >>> pB.pos_from(pA)
+    q(t)*N.x
+    >>> linear_pathway = LinearPathway(pA, pB)
+    >>> spring = LinearSpring(stiffness, linear_pathway)
+    >>> spring
+    LinearSpring(k, LinearPathway(pA, pB))
+
+    This spring will produce a force that is proportional to both its stiffness
+    and the pathway's length. Note that this force is negative as SymPy's sign
+    convention for actuators is that negative forces are contractile.
+
+    >>> spring.force
+    -k*sqrt(q(t)**2)
+
+    To create a linear spring with a non-zero equilibrium length, an expression
+    (or symbol) can be passed to the ``equilibrium_length`` parameter on
+    construction on a ``LinearSpring`` instance. Let's create a symbol ``l``
+    to denote a non-zero equilibrium length and create another linear spring.
+
+    >>> l = symbols('l')
+    >>> spring = LinearSpring(stiffness, linear_pathway, equilibrium_length=l)
+    >>> spring
+    LinearSpring(k, LinearPathway(pA, pB), equilibrium_length=l)
+
+    The spring force of this new spring is again proportional to both its
+    stiffness and the pathway's length. However, the spring will not produce
+    any force when ``q(t)`` equals ``l``. Note that the force will become
+    expansile when ``q(t)`` is less than ``l``, as expected.
+
+    >>> spring.force
+    -k*(-l + sqrt(q(t)**2))
+
+    Parameters
+    ==========
+
+    stiffness : Expr
+        The spring constant.
+    pathway : PathwayBase
+        The pathway that the actuator follows. This must be an instance of a
+        concrete subclass of ``PathwayBase``, e.g. ``LinearPathway``.
+    equilibrium_length : Expr, optional
+        The length at which the spring is in equilibrium, i.e. it produces no
+        force. The default value is 0, i.e. the spring force is a linear
+        function of the pathway's length with no constant offset.
+
+    See Also
+    ========
+
+    ForceActuator: force-producing actuator (superclass of ``LinearSpring``).
+    LinearPathway: straight-line pathway between a pair of points.
+
+    """
+
+    def __init__(self, stiffness, pathway, equilibrium_length=S.Zero):
+        """Initializer for ``LinearSpring``.
+
+        Parameters
+        ==========
+
+        stiffness : Expr
+            The spring constant.
+        pathway : PathwayBase
+            The pathway that the actuator follows. This must be an instance of
+            a concrete subclass of ``PathwayBase``, e.g. ``LinearPathway``.
+        equilibrium_length : Expr, optional
+            The length at which the spring is in equilibrium, i.e. it produces
+            no force. The default value is 0, i.e. the spring force is a linear
+            function of the pathway's length with no constant offset.
+
+        """
+        self.stiffness = stiffness
+        self.pathway = pathway
+        self.equilibrium_length = equilibrium_length
+
+    @property
+    def force(self):
+        """The spring force produced by the linear spring."""
+        return -self.stiffness*(self.pathway.length - self.equilibrium_length)
+
+    @force.setter
+    def force(self, force):
+        raise AttributeError('Can\'t set computed attribute `force`.')
+
+    @property
+    def stiffness(self):
+        """The spring constant for the linear spring."""
+        return self._stiffness
+
+    @stiffness.setter
+    def stiffness(self, stiffness):
+        if hasattr(self, '_stiffness'):
+            msg = (
+                f'Can\'t set attribute `stiffness` to {repr(stiffness)} as it '
+                f'is immutable.'
+            )
+            raise AttributeError(msg)
+        self._stiffness = sympify(stiffness, strict=True)
+
+    @property
+    def equilibrium_length(self):
+        """The length of the spring at which it produces no force."""
+        return self._equilibrium_length
+
+    @equilibrium_length.setter
+    def equilibrium_length(self, equilibrium_length):
+        if hasattr(self, '_equilibrium_length'):
+            msg = (
+                f'Can\'t set attribute `equilibrium_length` to '
+                f'{repr(equilibrium_length)} as it is immutable.'
+            )
+            raise AttributeError(msg)
+        self._equilibrium_length = sympify(equilibrium_length, strict=True)
+
+    def __repr__(self):
+        """Representation of a ``LinearSpring``."""
+        string = f'{self.__class__.__name__}({self.stiffness}, {self.pathway}'
+        if self.equilibrium_length == S.Zero:
+            string += ')'
+        else:
+            string += f', equilibrium_length={self.equilibrium_length})'
+        return string
+
+
+class LinearDamper(ForceActuator):
+    """A damper whose force is a linear function of its extension velocity.
+
+    Explanation
+    ===========
+
+    Note that the "linear" in the name ``LinearDamper`` refers to the fact that
+    the damping force is a linear function of the damper's rate of change in
+    its length. I.e. for a linear damper with damping ``c`` and extension
+    velocity ``v``, the damping force will be ``-c*v``, which is a linear
+    function in ``v``. To create a damper that follows a linear, or straight,
+    pathway between its two ends, a ``LinearPathway`` instance needs to be
+    passed to the ``pathway`` parameter.
+
+    A ``LinearDamper`` is a subclass of ``ForceActuator`` and so follows the
+    same sign conventions for length, extension velocity, and the direction of
+    the forces it applies to its points of attachment on bodies. The sign
+    convention for the direction of forces is such that, for the case where a
+    linear damper is instantiated with a ``LinearPathway`` instance as its
+    pathway, they act to push the two ends of the damper away from one another.
+    Because dampers produce a force that opposes the direction of change in
+    length, when extension velocity is positive the scalar portions of the
+    forces applied at the two endpoints are negative in order to flip the sign
+    of the forces on the endpoints wen converted into vector quantities. When
+    extension velocity is negative (i.e. when the damper is shortening), the
+    scalar portions of the fofces applied are also negative so that the signs
+    cancel producing forces on the endpoints that are in the same direction as
+    the positive sign convention for the forces at the endpoints of the pathway
+    (i.e. they act to push the endpoints away from one another). The following
+    diagram shows the positive force sense and the distance between the
+    points::
+
+       P           Q
+       o<--- F --->o
+       |           |
+       |<--l(t)--->|
+
+    Examples
+    ========
+
+    To construct a linear damper, an expression (or symbol) must be supplied to
+    represent the damping coefficient of the damper (we'll use the symbol
+    ``c``), alongside a pathway specifying its line of action. Let's also
+    create a global reference frame and spatially fix one of the points in it
+    while setting the other to be positioned such that it can freely move in
+    the frame's x direction specified by the coordinate ``q``. The velocity
+    that the two points move away from one another can be specified by the
+    coordinate ``u`` where ``u`` is the first time derivative of ``q``
+    (i.e., ``u = Derivative(q(t), t)``).
+
+    >>> from sympy import symbols
+    >>> from sympy.physics.mechanics import (LinearDamper, LinearPathway,
+    ...     Point, ReferenceFrame)
+    >>> from sympy.physics.vector import dynamicsymbols
+    >>> N = ReferenceFrame('N')
+    >>> q = dynamicsymbols('q')
+    >>> damping = symbols('c')
+    >>> pA, pB = Point('pA'), Point('pB')
+    >>> pA.set_vel(N, 0)
+    >>> pB.set_pos(pA, q*N.x)
+    >>> pB.pos_from(pA)
+    q(t)*N.x
+    >>> pB.vel(N)
+    Derivative(q(t), t)*N.x
+    >>> linear_pathway = LinearPathway(pA, pB)
+    >>> damper = LinearDamper(damping, linear_pathway)
+    >>> damper
+    LinearDamper(c, LinearPathway(pA, pB))
+
+    This damper will produce a force that is proportional to both its damping
+    coefficient and the pathway's extension length. Note that this force is
+    negative as SymPy's sign convention for actuators is that negative forces
+    are contractile and the damping force of the damper will oppose the
+    direction of length change.
+
+    >>> damper.force
+    -c*sqrt(q(t)**2)*Derivative(q(t), t)/q(t)
+
+    Parameters
+    ==========
+
+    damping : Expr
+        The damping constant.
+    pathway : PathwayBase
+        The pathway that the actuator follows. This must be an instance of a
+        concrete subclass of ``PathwayBase``, e.g. ``LinearPathway``.
+
+    See Also
+    ========
+
+    ForceActuator: force-producing actuator (superclass of ``LinearDamper``).
+    LinearPathway: straight-line pathway between a pair of points.
+
+    """
+
+    def __init__(self, damping, pathway):
+        """Initializer for ``LinearDamper``.
+
+        Parameters
+        ==========
+
+        damping : Expr
+            The damping constant.
+        pathway : PathwayBase
+            The pathway that the actuator follows. This must be an instance of
+            a concrete subclass of ``PathwayBase``, e.g. ``LinearPathway``.
+
+        """
+        self.damping = damping
+        self.pathway = pathway
+
+    @property
+    def force(self):
+        """The damping force produced by the linear damper."""
+        return -self.damping*self.pathway.extension_velocity
+
+    @force.setter
+    def force(self, force):
+        raise AttributeError('Can\'t set computed attribute `force`.')
+
+    @property
+    def damping(self):
+        """The damping constant for the linear damper."""
+        return self._damping
+
+    @damping.setter
+    def damping(self, damping):
+        if hasattr(self, '_damping'):
+            msg = (
+                f'Can\'t set attribute `damping` to {repr(damping)} as it is '
+                f'immutable.'
+            )
+            raise AttributeError(msg)
+        self._damping = sympify(damping, strict=True)
+
+    def __repr__(self):
+        """Representation of a ``LinearDamper``."""
+        return f'{self.__class__.__name__}({self.damping}, {self.pathway})'
+
+
+class TorqueActuator(ActuatorBase):
+    """Torque-producing actuator.
+
+    Explanation
+    ===========
+
+    A ``TorqueActuator`` is an actuator that produces a pair of equal and
+    opposite torques on a pair of bodies.
+
+    Examples
+    ========
+
+    To construct a torque actuator, an expression (or symbol) must be supplied
+    to represent the torque it can produce, alongside a vector specifying the
+    axis about which the torque will act, and a pair of frames on which the
+    torque will act.
+
+    >>> from sympy import symbols
+    >>> from sympy.physics.mechanics import (ReferenceFrame, RigidBody,
+    ...     TorqueActuator)
+    >>> N = ReferenceFrame('N')
+    >>> A = ReferenceFrame('A')
+    >>> torque = symbols('T')
+    >>> axis = N.z
+    >>> parent = RigidBody('parent', frame=N)
+    >>> child = RigidBody('child', frame=A)
+    >>> bodies = (child, parent)
+    >>> actuator = TorqueActuator(torque, axis, *bodies)
+    >>> actuator
+    TorqueActuator(T, axis=N.z, target_frame=A, reaction_frame=N)
+
+    Note that because torques actually act on frames, not bodies,
+    ``TorqueActuator`` will extract the frame associated with a ``RigidBody``
+    when one is passed instead of a ``ReferenceFrame``.
+
+    Parameters
+    ==========
+
+    torque : Expr
+        The scalar expression defining the torque that the actuator produces.
+    axis : Vector
+        The axis about which the actuator applies torques.
+    target_frame : ReferenceFrame | RigidBody
+        The primary frame on which the actuator will apply the torque.
+    reaction_frame : ReferenceFrame | RigidBody | None
+        The secondary frame on which the actuator will apply the torque. Note
+        that the (equal and opposite) reaction torque is applied to this frame.
+
+    """
+
+    def __init__(self, torque, axis, target_frame, reaction_frame=None):
+        """Initializer for ``TorqueActuator``.
+
+        Parameters
+        ==========
+
+        torque : Expr
+            The scalar expression defining the torque that the actuator
+            produces.
+        axis : Vector
+            The axis about which the actuator applies torques.
+        target_frame : ReferenceFrame | RigidBody
+            The primary frame on which the actuator will apply the torque.
+        reaction_frame : ReferenceFrame | RigidBody | None
+           The secondary frame on which the actuator will apply the torque.
+           Note that the (equal and opposite) reaction torque is applied to
+           this frame.
+
+        """
+        self.torque = torque
+        self.axis = axis
+        self.target_frame = target_frame
+        self.reaction_frame = reaction_frame
+
+    @classmethod
+    def at_pin_joint(cls, torque, pin_joint):
+        """Alternate construtor to instantiate from a ``PinJoint`` instance.
+
+        Examples
+        ========
+
+        To create a pin joint the ``PinJoint`` class requires a name, parent
+        body, and child body to be passed to its constructor. It is also
+        possible to control the joint axis using the ``joint_axis`` keyword
+        argument. In this example let's use the parent body's reference frame's
+        z-axis as the joint axis.
+
+        >>> from sympy.physics.mechanics import (PinJoint, ReferenceFrame,
+        ...     RigidBody, TorqueActuator)
+        >>> N = ReferenceFrame('N')
+        >>> A = ReferenceFrame('A')
+        >>> parent = RigidBody('parent', frame=N)
+        >>> child = RigidBody('child', frame=A)
+        >>> pin_joint = PinJoint(
+        ...     'pin',
+        ...     parent,
+        ...     child,
+        ...     joint_axis=N.z,
+        ... )
+
+        Let's also create a symbol ``T`` that will represent the torque applied
+        by the torque actuator.
+
+        >>> from sympy import symbols
+        >>> torque = symbols('T')
+
+        To create the torque actuator from the ``torque`` and ``pin_joint``
+        variables previously instantiated, these can be passed to the alternate
+        constructor class method ``at_pin_joint`` of the ``TorqueActuator``
+        class. It should be noted that a positive torque will cause a positive
+        displacement of the joint coordinate or that the torque is applied on
+        the child body with a reaction torque on the parent.
+
+        >>> actuator = TorqueActuator.at_pin_joint(torque, pin_joint)
+        >>> actuator
+        TorqueActuator(T, axis=N.z, target_frame=A, reaction_frame=N)
+
+        Parameters
+        ==========
+
+        torque : Expr
+            The scalar expression defining the torque that the actuator
+            produces.
+        pin_joint : PinJoint
+            The pin joint, and by association the parent and child bodies, on
+            which the torque actuator will act. The pair of bodies acted upon
+            by the torque actuator are the parent and child bodies of the pin
+            joint, with the child acting as the reaction body. The pin joint's
+            axis is used as the axis about which the torque actuator will apply
+            its torque.
+
+        """
+        if not isinstance(pin_joint, PinJoint):
+            msg = (
+                f'Value {repr(pin_joint)} passed to `pin_joint` was of type '
+                f'{type(pin_joint)}, must be {PinJoint}.'
+            )
+            raise TypeError(msg)
+        return cls(
+            torque,
+            pin_joint.joint_axis,
+            pin_joint.child_interframe,
+            pin_joint.parent_interframe,
+        )
+
+    @property
+    def torque(self):
+        """The magnitude of the torque produced by the actuator."""
+        return self._torque
+
+    @torque.setter
+    def torque(self, torque):
+        if hasattr(self, '_torque'):
+            msg = (
+                f'Can\'t set attribute `torque` to {repr(torque)} as it is '
+                f'immutable.'
+            )
+            raise AttributeError(msg)
+        self._torque = sympify(torque, strict=True)
+
+    @property
+    def axis(self):
+        """The axis about which the torque acts."""
+        return self._axis
+
+    @axis.setter
+    def axis(self, axis):
+        if hasattr(self, '_axis'):
+            msg = (
+                f'Can\'t set attribute `axis` to {repr(axis)} as it is '
+                f'immutable.'
+            )
+            raise AttributeError(msg)
+        if not isinstance(axis, Vector):
+            msg = (
+                f'Value {repr(axis)} passed to `axis` was of type '
+                f'{type(axis)}, must be {Vector}.'
+            )
+            raise TypeError(msg)
+        self._axis = axis
+
+    @property
+    def target_frame(self):
+        """The primary reference frames on which the torque will act."""
+        return self._target_frame
+
+    @target_frame.setter
+    def target_frame(self, target_frame):
+        if hasattr(self, '_target_frame'):
+            msg = (
+                f'Can\'t set attribute `target_frame` to {repr(target_frame)} '
+                f'as it is immutable.'
+            )
+            raise AttributeError(msg)
+        if isinstance(target_frame, RigidBody):
+            target_frame = target_frame.frame
+        elif not isinstance(target_frame, ReferenceFrame):
+            msg = (
+                f'Value {repr(target_frame)} passed to `target_frame` was of '
+                f'type {type(target_frame)}, must be {ReferenceFrame}.'
+            )
+            raise TypeError(msg)
+        self._target_frame = target_frame
+
+    @property
+    def reaction_frame(self):
+        """The primary reference frames on which the torque will act."""
+        return self._reaction_frame
+
+    @reaction_frame.setter
+    def reaction_frame(self, reaction_frame):
+        if hasattr(self, '_reaction_frame'):
+            msg = (
+                f'Can\'t set attribute `reaction_frame` to '
+                f'{repr(reaction_frame)} as it is immutable.'
+            )
+            raise AttributeError(msg)
+        if isinstance(reaction_frame, RigidBody):
+            reaction_frame = reaction_frame.frame
+        elif (
+            not isinstance(reaction_frame, ReferenceFrame)
+            and reaction_frame is not None
+        ):
+            msg = (
+                f'Value {repr(reaction_frame)} passed to `reaction_frame` was '
+                f'of type {type(reaction_frame)}, must be {ReferenceFrame}.'
+            )
+            raise TypeError(msg)
+        self._reaction_frame = reaction_frame
+
+    def to_loads(self):
+        """Loads required by the equations of motion method classes.
+
+        Explanation
+        ===========
+
+        ``KanesMethod`` requires a list of ``Point``-``Vector`` tuples to be
+        passed to the ``loads`` parameters of its ``kanes_equations`` method
+        when constructing the equations of motion. This method acts as a
+        utility to produce the correctly-structred pairs of points and vectors
+        required so that these can be easily concatenated with other items in
+        the list of loads and passed to ``KanesMethod.kanes_equations``. These
+        loads are also in the correct form to also be passed to the other
+        equations of motion method classes, e.g. ``LagrangesMethod``.
+
+        Examples
+        ========
+
+        The below example shows how to generate the loads produced by a torque
+        actuator that acts on a pair of bodies attached by a pin joint.
+
+        >>> from sympy import symbols
+        >>> from sympy.physics.mechanics import (PinJoint, ReferenceFrame,
+        ...     RigidBody, TorqueActuator)
+        >>> torque = symbols('T')
+        >>> N = ReferenceFrame('N')
+        >>> A = ReferenceFrame('A')
+        >>> parent = RigidBody('parent', frame=N)
+        >>> child = RigidBody('child', frame=A)
+        >>> pin_joint = PinJoint(
+        ...     'pin',
+        ...     parent,
+        ...     child,
+        ...     joint_axis=N.z,
+        ... )
+        >>> actuator = TorqueActuator.at_pin_joint(torque, pin_joint)
+
+        The forces produces by the damper can be generated by calling the
+        ``to_loads`` method.
+
+        >>> actuator.to_loads()
+        [(A, T*N.z), (N, - T*N.z)]
+
+        Alternatively, if a torque actuator is created without a reaction frame
+        then the loads returned by the ``to_loads`` method will contain just
+        the single load acting on the target frame.
+
+        >>> actuator = TorqueActuator(torque, N.z, N)
+        >>> actuator.to_loads()
+        [(N, T*N.z)]
+
+        """
+        loads = [
+            Torque(self.target_frame, self.torque*self.axis),
+        ]
+        if self.reaction_frame is not None:
+            loads.append(Torque(self.reaction_frame, -self.torque*self.axis))
+        return loads
+
+    def __repr__(self):
+        """Representation of a ``TorqueActuator``."""
+        string = (
+            f'{self.__class__.__name__}({self.torque}, axis={self.axis}, '
+            f'target_frame={self.target_frame}'
+        )
+        if self.reaction_frame is not None:
+            string += f', reaction_frame={self.reaction_frame})'
+        else:
+            string += ')'
+        return string
+
+
+class DuffingSpring(ForceActuator):
+    """A nonlinear spring based on the Duffing equation.
+
+    Explanation
+    ===========
+
+    Here, ``DuffingSpring`` represents the force exerted by a nonlinear spring based on the Duffing equation:
+    F = -beta*x-alpha*x**3, where x is the displacement from the equilibrium position, beta is the linear spring constant,
+    and alpha is the coefficient for the nonlinear cubic term.
+
+    Parameters
+    ==========
+
+    linear_stiffness : Expr
+        The linear stiffness coefficient (beta).
+    nonlinear_stiffness : Expr
+        The nonlinear stiffness coefficient (alpha).
+    pathway : PathwayBase
+        The pathway that the actuator follows.
+    equilibrium_length : Expr, optional
+        The length at which the spring is in equilibrium (x).
+    """
+
+    def __init__(self, linear_stiffness, nonlinear_stiffness, pathway, equilibrium_length=S.Zero):
+        self.linear_stiffness = sympify(linear_stiffness, strict=True)
+        self.nonlinear_stiffness = sympify(nonlinear_stiffness, strict=True)
+        self.equilibrium_length = sympify(equilibrium_length, strict=True)
+
+        if not isinstance(pathway, PathwayBase):
+            raise TypeError("pathway must be an instance of PathwayBase.")
+        self._pathway = pathway
+
+    @property
+    def linear_stiffness(self):
+        return self._linear_stiffness
+
+    @linear_stiffness.setter
+    def linear_stiffness(self, linear_stiffness):
+        if hasattr(self, '_linear_stiffness'):
+            msg = (
+                f'Can\'t set attribute `linear_stiffness` to '
+                f'{repr(linear_stiffness)} as it is immutable.'
+            )
+            raise AttributeError(msg)
+        self._linear_stiffness = sympify(linear_stiffness, strict=True)
+
+    @property
+    def nonlinear_stiffness(self):
+        return self._nonlinear_stiffness
+
+    @nonlinear_stiffness.setter
+    def nonlinear_stiffness(self, nonlinear_stiffness):
+        if hasattr(self, '_nonlinear_stiffness'):
+            msg = (
+                f'Can\'t set attribute `nonlinear_stiffness` to '
+                f'{repr(nonlinear_stiffness)} as it is immutable.'
+            )
+            raise AttributeError(msg)
+        self._nonlinear_stiffness = sympify(nonlinear_stiffness, strict=True)
+
+    @property
+    def pathway(self):
+        return self._pathway
+
+    @pathway.setter
+    def pathway(self, pathway):
+        if hasattr(self, '_pathway'):
+            msg = (
+                f'Can\'t set attribute `pathway` to {repr(pathway)} as it is '
+                f'immutable.'
+            )
+            raise AttributeError(msg)
+        if not isinstance(pathway, PathwayBase):
+            msg = (
+                f'Value {repr(pathway)} passed to `pathway` was of type '
+                f'{type(pathway)}, must be {PathwayBase}.'
+            )
+            raise TypeError(msg)
+        self._pathway = pathway
+
+    @property
+    def equilibrium_length(self):
+        return self._equilibrium_length
+
+    @equilibrium_length.setter
+    def equilibrium_length(self, equilibrium_length):
+        if hasattr(self, '_equilibrium_length'):
+            msg = (
+                f'Can\'t set attribute `equilibrium_length` to '
+                f'{repr(equilibrium_length)} as it is immutable.'
+            )
+            raise AttributeError(msg)
+        self._equilibrium_length = sympify(equilibrium_length, strict=True)
+
+    @property
+    def force(self):
+        """The force produced by the Duffing spring."""
+        displacement = self.pathway.length - self.equilibrium_length
+        return -self.linear_stiffness * displacement - self.nonlinear_stiffness * displacement**3
+
+    @force.setter
+    def force(self, force):
+        if hasattr(self, '_force'):
+            msg = (
+                f'Can\'t set attribute `force` to {repr(force)} as it is '
+                f'immutable.'
+            )
+            raise AttributeError(msg)
+        self._force = sympify(force, strict=True)
+
+    def __repr__(self):
+        return (f"{self.__class__.__name__}("
+                f"{self.linear_stiffness}, {self.nonlinear_stiffness}, {self.pathway}, "
+                f"equilibrium_length={self.equilibrium_length})")

lib/python3.12/site-packages/sympy/physics/mechanics/body.py

@@ -0,0 +1,710 @@
+from sympy import Symbol
+from sympy.physics.vector import Point, Vector, ReferenceFrame, Dyadic
+from sympy.physics.mechanics import RigidBody, Particle, Inertia
+from sympy.physics.mechanics.body_base import BodyBase
+from sympy.utilities.exceptions import sympy_deprecation_warning
+
+__all__ = ['Body']
+
+
+# XXX: We use type:ignore because the classes RigidBody and Particle have
+# inconsistent parallel axis methods that take different numbers of arguments.
+class Body(RigidBody, Particle):  # type: ignore
+    """
+    Body is a common representation of either a RigidBody or a Particle SymPy
+    object depending on what is passed in during initialization. If a mass is
+    passed in and central_inertia is left as None, the Particle object is
+    created. Otherwise a RigidBody object will be created.
+
+    .. deprecated:: 1.13
+        The Body class is deprecated. Its functionality is captured by
+        :class:`~.RigidBody` and :class:`~.Particle`.
+
+    Explanation
+    ===========
+
+    The attributes that Body possesses will be the same as a Particle instance
+    or a Rigid Body instance depending on which was created. Additional
+    attributes are listed below.
+
+    Attributes
+    ==========
+
+    name : string
+        The body's name
+    masscenter : Point
+        The point which represents the center of mass of the rigid body
+    frame : ReferenceFrame
+        The reference frame which the body is fixed in
+    mass : Sympifyable
+        The body's mass
+    inertia : (Dyadic, Point)
+        The body's inertia around its center of mass. This attribute is specific
+        to the rigid body form of Body and is left undefined for the Particle
+        form
+    loads : iterable
+        This list contains information on the different loads acting on the
+        Body. Forces are listed as a (point, vector) tuple and torques are
+        listed as (reference frame, vector) tuples.
+
+    Parameters
+    ==========
+
+    name : String
+        Defines the name of the body. It is used as the base for defining
+        body specific properties.
+    masscenter : Point, optional
+        A point that represents the center of mass of the body or particle.
+        If no point is given, a point is generated.
+    mass : Sympifyable, optional
+        A Sympifyable object which represents the mass of the body. If no
+        mass is passed, one is generated.
+    frame : ReferenceFrame, optional
+        The ReferenceFrame that represents the reference frame of the body.
+        If no frame is given, a frame is generated.
+    central_inertia : Dyadic, optional
+        Central inertia dyadic of the body. If none is passed while creating
+        RigidBody, a default inertia is generated.
+
+    Examples
+    ========
+
+    As Body has been deprecated, the following examples are for illustrative
+    purposes only. The functionality of Body is fully captured by
+    :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+    warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
+
+    Default behaviour. This results in the creation of a RigidBody object for
+    which the mass, mass center, frame and inertia attributes are given default
+    values. ::
+
+        >>> from sympy.physics.mechanics import Body
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     body = Body('name_of_body')
+
+    This next example demonstrates the code required to specify all of the
+    values of the Body object. Note this will also create a RigidBody version of
+    the Body object. ::
+
+        >>> from sympy import Symbol
+        >>> from sympy.physics.mechanics import ReferenceFrame, Point, inertia
+        >>> from sympy.physics.mechanics import Body
+        >>> mass = Symbol('mass')
+        >>> masscenter = Point('masscenter')
+        >>> frame = ReferenceFrame('frame')
+        >>> ixx = Symbol('ixx')
+        >>> body_inertia = inertia(frame, ixx, 0, 0)
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     body = Body('name_of_body', masscenter, mass, frame, body_inertia)
+
+    The minimal code required to create a Particle version of the Body object
+    involves simply passing in a name and a mass. ::
+
+        >>> from sympy import Symbol
+        >>> from sympy.physics.mechanics import Body
+        >>> mass = Symbol('mass')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     body = Body('name_of_body', mass=mass)
+
+    The Particle version of the Body object can also receive a masscenter point
+    and a reference frame, just not an inertia.
+    """
+
+    def __init__(self, name, masscenter=None, mass=None, frame=None,
+                 central_inertia=None):
+        sympy_deprecation_warning(
+            """
+            Support for the Body class has been removed, as its functionality is
+            fully captured by RigidBody and Particle.
+            """,
+            deprecated_since_version="1.13",
+            active_deprecations_target="deprecated-mechanics-body-class"
+        )
+
+        self._loads = []
+
+        if frame is None:
+            frame = ReferenceFrame(name + '_frame')
+
+        if masscenter is None:
+            masscenter = Point(name + '_masscenter')
+
+        if central_inertia is None and mass is None:
+            ixx = Symbol(name + '_ixx')
+            iyy = Symbol(name + '_iyy')
+            izz = Symbol(name + '_izz')
+            izx = Symbol(name + '_izx')
+            ixy = Symbol(name + '_ixy')
+            iyz = Symbol(name + '_iyz')
+            _inertia = Inertia.from_inertia_scalars(masscenter, frame, ixx, iyy,
+                                                    izz, ixy, iyz, izx)
+        else:
+            _inertia = (central_inertia, masscenter)
+
+        if mass is None:
+            _mass = Symbol(name + '_mass')
+        else:
+            _mass = mass
+
+        masscenter.set_vel(frame, 0)
+
+        # If user passes masscenter and mass then a particle is created
+        # otherwise a rigidbody. As a result a body may or may not have inertia.
+        # Note: BodyBase.__init__ is used to prevent problems with super() calls in
+        # Particle and RigidBody arising due to multiple inheritance.
+        if central_inertia is None and mass is not None:
+            BodyBase.__init__(self, name, masscenter, _mass)
+            self.frame = frame
+            self._central_inertia = Dyadic(0)
+        else:
+            BodyBase.__init__(self, name, masscenter, _mass)
+            self.frame = frame
+            self.inertia = _inertia
+
+    def __repr__(self):
+        if self.is_rigidbody:
+            return RigidBody.__repr__(self)
+        return Particle.__repr__(self)
+
+    @property
+    def loads(self):
+        return self._loads
+
+    @property
+    def x(self):
+        """The basis Vector for the Body, in the x direction."""
+        return self.frame.x
+
+    @property
+    def y(self):
+        """The basis Vector for the Body, in the y direction."""
+        return self.frame.y
+
+    @property
+    def z(self):
+        """The basis Vector for the Body, in the z direction."""
+        return self.frame.z
+
+    @property
+    def inertia(self):
+        """The body's inertia about a point; stored as (Dyadic, Point)."""
+        if self.is_rigidbody:
+            return RigidBody.inertia.fget(self)
+        return (self.central_inertia, self.masscenter)
+
+    @inertia.setter
+    def inertia(self, I):
+        RigidBody.inertia.fset(self, I)
+
+    @property
+    def is_rigidbody(self):
+        if hasattr(self, '_inertia'):
+            return True
+        return False
+
+    def kinetic_energy(self, frame):
+        """Kinetic energy of the body.
+
+        Parameters
+        ==========
+
+        frame : ReferenceFrame or Body
+            The Body's angular velocity and the velocity of it's mass
+            center are typically defined with respect to an inertial frame but
+            any relevant frame in which the velocities are known can be supplied.
+
+        Examples
+        ========
+
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
+        >>> from sympy.physics.mechanics import Body, ReferenceFrame, Point
+        >>> from sympy import symbols
+        >>> m, v, r, omega = symbols('m v r omega')
+        >>> N = ReferenceFrame('N')
+        >>> O = Point('O')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     P = Body('P', masscenter=O, mass=m)
+        >>> P.masscenter.set_vel(N, v * N.y)
+        >>> P.kinetic_energy(N)
+        m*v**2/2
+
+        >>> N = ReferenceFrame('N')
+        >>> b = ReferenceFrame('b')
+        >>> b.set_ang_vel(N, omega * b.x)
+        >>> P = Point('P')
+        >>> P.set_vel(N, v * N.x)
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     B = Body('B', masscenter=P, frame=b)
+        >>> B.kinetic_energy(N)
+        B_ixx*omega**2/2 + B_mass*v**2/2
+
+        See Also
+        ========
+
+        sympy.physics.mechanics : Particle, RigidBody
+
+        """
+        if isinstance(frame, Body):
+            frame = Body.frame
+        if self.is_rigidbody:
+            return RigidBody(self.name, self.masscenter, self.frame, self.mass,
+                            (self.central_inertia, self.masscenter)).kinetic_energy(frame)
+        return Particle(self.name, self.masscenter, self.mass).kinetic_energy(frame)
+
+    def apply_force(self, force, point=None, reaction_body=None, reaction_point=None):
+        """Add force to the body(s).
+
+        Explanation
+        ===========
+
+        Applies the force on self or equal and opposite forces on
+        self and other body if both are given on the desired point on the bodies.
+        The force applied on other body is taken opposite of self, i.e, -force.
+
+        Parameters
+        ==========
+
+        force: Vector
+            The force to be applied.
+        point: Point, optional
+            The point on self on which force is applied.
+            By default self's masscenter.
+        reaction_body: Body, optional
+            Second body on which equal and opposite force
+            is to be applied.
+        reaction_point : Point, optional
+            The point on other body on which equal and opposite
+            force is applied. By default masscenter of other body.
+
+        Example
+        =======
+
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
+        >>> from sympy import symbols
+        >>> from sympy.physics.mechanics import Body, Point, dynamicsymbols
+        >>> m, g = symbols('m g')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     B = Body('B')
+        >>> force1 = m*g*B.z
+        >>> B.apply_force(force1) #Applying force on B's masscenter
+        >>> B.loads
+        [(B_masscenter, g*m*B_frame.z)]
+
+        We can also remove some part of force from any point on the body by
+        adding the opposite force to the body on that point.
+
+        >>> f1, f2 = dynamicsymbols('f1 f2')
+        >>> P = Point('P') #Considering point P on body B
+        >>> B.apply_force(f1*B.x + f2*B.y, P)
+        >>> B.loads
+        [(B_masscenter, g*m*B_frame.z), (P, f1(t)*B_frame.x + f2(t)*B_frame.y)]
+
+        Let's remove f1 from point P on body B.
+
+        >>> B.apply_force(-f1*B.x, P)
+        >>> B.loads
+        [(B_masscenter, g*m*B_frame.z), (P, f2(t)*B_frame.y)]
+
+        To further demonstrate the use of ``apply_force`` attribute,
+        consider two bodies connected through a spring.
+
+        >>> from sympy.physics.mechanics import Body, dynamicsymbols
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     N = Body('N') #Newtonion Frame
+        >>> x = dynamicsymbols('x')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     B1 = Body('B1')
+        ...     B2 = Body('B2')
+        >>> spring_force = x*N.x
+
+        Now let's apply equal and opposite spring force to the bodies.
+
+        >>> P1 = Point('P1')
+        >>> P2 = Point('P2')
+        >>> B1.apply_force(spring_force, point=P1, reaction_body=B2, reaction_point=P2)
+
+        We can check the loads(forces) applied to bodies now.
+
+        >>> B1.loads
+        [(P1, x(t)*N_frame.x)]
+        >>> B2.loads
+        [(P2, - x(t)*N_frame.x)]
+
+        Notes
+        =====
+
+        If a new force is applied to a body on a point which already has some
+        force applied on it, then the new force is added to the already applied
+        force on that point.
+
+        """
+
+        if not isinstance(point, Point):
+            if point is None:
+                point = self.masscenter  # masscenter
+            else:
+                raise TypeError("Force must be applied to a point on the body.")
+        if not isinstance(force, Vector):
+            raise TypeError("Force must be a vector.")
+
+        if reaction_body is not None:
+            reaction_body.apply_force(-force, point=reaction_point)
+
+        for load in self._loads:
+            if point in load:
+                force += load[1]
+                self._loads.remove(load)
+                break
+
+        self._loads.append((point, force))
+
+    def apply_torque(self, torque, reaction_body=None):
+        """Add torque to the body(s).
+
+        Explanation
+        ===========
+
+        Applies the torque on self or equal and opposite torques on
+        self and other body if both are given.
+        The torque applied on other body is taken opposite of self,
+        i.e, -torque.
+
+        Parameters
+        ==========
+
+        torque: Vector
+            The torque to be applied.
+        reaction_body: Body, optional
+            Second body on which equal and opposite torque
+            is to be applied.
+
+        Example
+        =======
+
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
+        >>> from sympy import symbols
+        >>> from sympy.physics.mechanics import Body, dynamicsymbols
+        >>> t = symbols('t')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     B = Body('B')
+        >>> torque1 = t*B.z
+        >>> B.apply_torque(torque1)
+        >>> B.loads
+        [(B_frame, t*B_frame.z)]
+
+        We can also remove some part of torque from the body by
+        adding the opposite torque to the body.
+
+        >>> t1, t2 = dynamicsymbols('t1 t2')
+        >>> B.apply_torque(t1*B.x + t2*B.y)
+        >>> B.loads
+        [(B_frame, t1(t)*B_frame.x + t2(t)*B_frame.y + t*B_frame.z)]
+
+        Let's remove t1 from Body B.
+
+        >>> B.apply_torque(-t1*B.x)
+        >>> B.loads
+        [(B_frame, t2(t)*B_frame.y + t*B_frame.z)]
+
+        To further demonstrate the use, let us consider two bodies such that
+        a torque `T` is acting on one body, and `-T` on the other.
+
+        >>> from sympy.physics.mechanics import Body, dynamicsymbols
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     N = Body('N') #Newtonion frame
+        ...     B1 = Body('B1')
+        ...     B2 = Body('B2')
+        >>> v = dynamicsymbols('v')
+        >>> T = v*N.y #Torque
+
+        Now let's apply equal and opposite torque to the bodies.
+
+        >>> B1.apply_torque(T, B2)
+
+        We can check the loads (torques) applied to bodies now.
+
+        >>> B1.loads
+        [(B1_frame, v(t)*N_frame.y)]
+        >>> B2.loads
+        [(B2_frame, - v(t)*N_frame.y)]
+
+        Notes
+        =====
+
+        If a new torque is applied on body which already has some torque applied on it,
+        then the new torque is added to the previous torque about the body's frame.
+
+        """
+
+        if not isinstance(torque, Vector):
+            raise TypeError("A Vector must be supplied to add torque.")
+
+        if reaction_body is not None:
+            reaction_body.apply_torque(-torque)
+
+        for load in self._loads:
+            if self.frame in load:
+                torque += load[1]
+                self._loads.remove(load)
+                break
+        self._loads.append((self.frame, torque))
+
+    def clear_loads(self):
+        """
+        Clears the Body's loads list.
+
+        Example
+        =======
+
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
+        >>> from sympy.physics.mechanics import Body
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     B = Body('B')
+        >>> force = B.x + B.y
+        >>> B.apply_force(force)
+        >>> B.loads
+        [(B_masscenter, B_frame.x + B_frame.y)]
+        >>> B.clear_loads()
+        >>> B.loads
+        []
+
+        """
+
+        self._loads = []
+
+    def remove_load(self, about=None):
+        """
+        Remove load about a point or frame.
+
+        Parameters
+        ==========
+
+        about : Point or ReferenceFrame, optional
+            The point about which force is applied,
+            and is to be removed.
+            If about is None, then the torque about
+            self's frame is removed.
+
+        Example
+        =======
+
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
+        >>> from sympy.physics.mechanics import Body, Point
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     B = Body('B')
+        >>> P = Point('P')
+        >>> f1 = B.x
+        >>> f2 = B.y
+        >>> B.apply_force(f1)
+        >>> B.apply_force(f2, P)
+        >>> B.loads
+        [(B_masscenter, B_frame.x), (P, B_frame.y)]
+
+        >>> B.remove_load(P)
+        >>> B.loads
+        [(B_masscenter, B_frame.x)]
+
+        """
+
+        if about is not None:
+            if not isinstance(about, Point):
+                raise TypeError('Load is applied about Point or ReferenceFrame.')
+        else:
+            about = self.frame
+
+        for load in self._loads:
+            if about in load:
+                self._loads.remove(load)
+                break
+
+    def masscenter_vel(self, body):
+        """
+        Returns the velocity of the mass center with respect to the provided
+        rigid body or reference frame.
+
+        Parameters
+        ==========
+
+        body: Body or ReferenceFrame
+            The rigid body or reference frame to calculate the velocity in.
+
+        Example
+        =======
+
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
+        >>> from sympy.physics.mechanics import Body
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     A = Body('A')
+        ...     B = Body('B')
+        >>> A.masscenter.set_vel(B.frame, 5*B.frame.x)
+        >>> A.masscenter_vel(B)
+        5*B_frame.x
+        >>> A.masscenter_vel(B.frame)
+        5*B_frame.x
+
+        """
+
+        if isinstance(body,  ReferenceFrame):
+            frame=body
+        elif isinstance(body, Body):
+            frame = body.frame
+        return self.masscenter.vel(frame)
+
+    def ang_vel_in(self, body):
+        """
+        Returns this body's angular velocity with respect to the provided
+        rigid body or reference frame.
+
+        Parameters
+        ==========
+
+        body: Body or ReferenceFrame
+            The rigid body or reference frame to calculate the angular velocity in.
+
+        Example
+        =======
+
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
+        >>> from sympy.physics.mechanics import Body, ReferenceFrame
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     A = Body('A')
+        >>> N = ReferenceFrame('N')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     B = Body('B', frame=N)
+        >>> A.frame.set_ang_vel(N, 5*N.x)
+        >>> A.ang_vel_in(B)
+        5*N.x
+        >>> A.ang_vel_in(N)
+        5*N.x
+
+        """
+
+        if isinstance(body,  ReferenceFrame):
+            frame=body
+        elif isinstance(body, Body):
+            frame = body.frame
+        return self.frame.ang_vel_in(frame)
+
+    def dcm(self, body):
+        """
+        Returns the direction cosine matrix of this body relative to the
+        provided rigid body or reference frame.
+
+        Parameters
+        ==========
+
+        body: Body or ReferenceFrame
+            The rigid body or reference frame to calculate the dcm.
+
+        Example
+        =======
+
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
+        >>> from sympy.physics.mechanics import Body
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     A = Body('A')
+        ...     B = Body('B')
+        >>> A.frame.orient_axis(B.frame, B.frame.x, 5)
+        >>> A.dcm(B)
+        Matrix([
+        [1,       0,      0],
+        [0,  cos(5), sin(5)],
+        [0, -sin(5), cos(5)]])
+        >>> A.dcm(B.frame)
+        Matrix([
+        [1,       0,      0],
+        [0,  cos(5), sin(5)],
+        [0, -sin(5), cos(5)]])
+
+        """
+
+        if isinstance(body,  ReferenceFrame):
+            frame=body
+        elif isinstance(body, Body):
+            frame = body.frame
+        return self.frame.dcm(frame)
+
+    def parallel_axis(self, point, frame=None):
+        """Returns the inertia dyadic of the body with respect to another
+        point.
+
+        Parameters
+        ==========
+
+        point : sympy.physics.vector.Point
+            The point to express the inertia dyadic about.
+        frame : sympy.physics.vector.ReferenceFrame
+            The reference frame used to construct the dyadic.
+
+        Returns
+        =======
+
+        inertia : sympy.physics.vector.Dyadic
+            The inertia dyadic of the rigid body expressed about the provided
+            point.
+
+        Example
+        =======
+
+        As Body has been deprecated, the following examples are for illustrative
+        purposes only. The functionality of Body is fully captured by
+        :class:`~.RigidBody` and :class:`~.Particle`. To ignore the deprecation
+        warning we can use the ignore_warnings context manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
+        >>> from sympy.physics.mechanics import Body
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     A = Body('A')
+        >>> P = A.masscenter.locatenew('point', 3 * A.x + 5 * A.y)
+        >>> A.parallel_axis(P).to_matrix(A.frame)
+        Matrix([
+        [A_ixx + 25*A_mass, A_ixy - 15*A_mass,             A_izx],
+        [A_ixy - 15*A_mass,  A_iyy + 9*A_mass,             A_iyz],
+        [            A_izx,             A_iyz, A_izz + 34*A_mass]])
+
+        """
+        if self.is_rigidbody:
+            return RigidBody.parallel_axis(self, point, frame)
+        return Particle.parallel_axis(self, point, frame)

lib/python3.12/site-packages/sympy/physics/mechanics/body_base.py

@@ -0,0 +1,94 @@
+from abc import ABC, abstractmethod
+from sympy import Symbol, sympify
+from sympy.physics.vector import Point
+
+__all__ = ['BodyBase']
+
+
+class BodyBase(ABC):
+    """Abstract class for body type objects."""
+    def __init__(self, name, masscenter=None, mass=None):
+        # Note: If frame=None, no auto-generated frame is created, because a
+        # Particle does not need to have a frame by default.
+        if not isinstance(name, str):
+            raise TypeError('Supply a valid name.')
+        self._name = name
+        if mass is None:
+            mass = Symbol(f'{name}_mass')
+        if masscenter is None:
+            masscenter = Point(f'{name}_masscenter')
+        self.mass = mass
+        self.masscenter = masscenter
+        self.potential_energy = 0
+        self.points = []
+
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return (f'{self.__class__.__name__}({repr(self.name)}, masscenter='
+                f'{repr(self.masscenter)}, mass={repr(self.mass)})')
+
+    @property
+    def name(self):
+        """The name of the body."""
+        return self._name
+
+    @property
+    def masscenter(self):
+        """The body's center of mass."""
+        return self._masscenter
+
+    @masscenter.setter
+    def masscenter(self, point):
+        if not isinstance(point, Point):
+            raise TypeError("The body's center of mass must be a Point object.")
+        self._masscenter = point
+
+    @property
+    def mass(self):
+        """The body's mass."""
+        return self._mass
+
+    @mass.setter
+    def mass(self, mass):
+        self._mass = sympify(mass)
+
+    @property
+    def potential_energy(self):
+        """The potential energy of the body.
+
+        Examples
+        ========
+
+        >>> from sympy.physics.mechanics import Particle, Point
+        >>> from sympy import symbols
+        >>> m, g, h = symbols('m g h')
+        >>> O = Point('O')
+        >>> P = Particle('P', O, m)
+        >>> P.potential_energy = m * g * h
+        >>> P.potential_energy
+        g*h*m
+
+        """
+        return self._potential_energy
+
+    @potential_energy.setter
+    def potential_energy(self, scalar):
+        self._potential_energy = sympify(scalar)
+
+    @abstractmethod
+    def kinetic_energy(self, frame):
+        pass
+
+    @abstractmethod
+    def linear_momentum(self, frame):
+        pass
+
+    @abstractmethod
+    def angular_momentum(self, point, frame):
+        pass
+
+    @abstractmethod
+    def parallel_axis(self, point, frame):
+        pass

lib/python3.12/site-packages/sympy/physics/mechanics/joint.py

@@ -0,0 +1,2188 @@
+# coding=utf-8
+
+from abc import ABC, abstractmethod
+
+from sympy import pi, Derivative, Matrix
+from sympy.core.function import AppliedUndef
+from sympy.physics.mechanics.body_base import BodyBase
+from sympy.physics.mechanics.functions import _validate_coordinates
+from sympy.physics.vector import (Vector, dynamicsymbols, cross, Point,
+                                  ReferenceFrame)
+from sympy.utilities.iterables import iterable
+from sympy.utilities.exceptions import sympy_deprecation_warning
+
+__all__ = ['Joint', 'PinJoint', 'PrismaticJoint', 'CylindricalJoint',
+           'PlanarJoint', 'SphericalJoint', 'WeldJoint']
+
+
+class Joint(ABC):
+    """Abstract base class for all specific joints.
+
+    Explanation
+    ===========
+
+    A joint subtracts degrees of freedom from a body. This is the base class
+    for all specific joints and holds all common methods acting as an interface
+    for all joints. Custom joint can be created by inheriting Joint class and
+    defining all abstract functions.
+
+    The abstract methods are:
+
+    - ``_generate_coordinates``
+    - ``_generate_speeds``
+    - ``_orient_frames``
+    - ``_set_angular_velocity``
+    - ``_set_linear_velocity``
+
+    Parameters
+    ==========
+
+    name : string
+        A unique name for the joint.
+    parent : Particle or RigidBody or Body
+        The parent body of joint.
+    child : Particle or RigidBody or Body
+        The child body of joint.
+    coordinates : iterable of dynamicsymbols, optional
+        Generalized coordinates of the joint.
+    speeds : iterable of dynamicsymbols, optional
+        Generalized speeds of joint.
+    parent_point : Point or Vector, optional
+        Attachment point where the joint is fixed to the parent body. If a
+        vector is provided, then the attachment point is computed by adding the
+        vector to the body's mass center. The default value is the parent's mass
+        center.
+    child_point : Point or Vector, optional
+        Attachment point where the joint is fixed to the child body. If a
+        vector is provided, then the attachment point is computed by adding the
+        vector to the body's mass center. The default value is the child's mass
+        center.
+    parent_axis : Vector, optional
+        .. deprecated:: 1.12
+            Axis fixed in the parent body which aligns with an axis fixed in the
+            child body. The default is the x axis of parent's reference frame.
+            For more information on this deprecation, see
+            :ref:`deprecated-mechanics-joint-axis`.
+    child_axis : Vector, optional
+        .. deprecated:: 1.12
+            Axis fixed in the child body which aligns with an axis fixed in the
+            parent body. The default is the x axis of child's reference frame.
+            For more information on this deprecation, see
+            :ref:`deprecated-mechanics-joint-axis`.
+    parent_interframe : ReferenceFrame, optional
+        Intermediate frame of the parent body with respect to which the joint
+        transformation is formulated. If a Vector is provided then an interframe
+        is created which aligns its X axis with the given vector. The default
+        value is the parent's own frame.
+    child_interframe : ReferenceFrame, optional
+        Intermediate frame of the child body with respect to which the joint
+        transformation is formulated. If a Vector is provided then an interframe
+        is created which aligns its X axis with the given vector. The default
+        value is the child's own frame.
+    parent_joint_pos : Point or Vector, optional
+        .. deprecated:: 1.12
+            This argument is replaced by parent_point and will be removed in a
+            future version.
+            See :ref:`deprecated-mechanics-joint-pos` for more information.
+    child_joint_pos : Point or Vector, optional
+        .. deprecated:: 1.12
+            This argument is replaced by child_point and will be removed in a
+            future version.
+            See :ref:`deprecated-mechanics-joint-pos` for more information.
+
+    Attributes
+    ==========
+
+    name : string
+        The joint's name.
+    parent : Particle or RigidBody or Body
+        The joint's parent body.
+    child : Particle or RigidBody or Body
+        The joint's child body.
+    coordinates : Matrix
+        Matrix of the joint's generalized coordinates.
+    speeds : Matrix
+        Matrix of the joint's generalized speeds.
+    parent_point : Point
+        Attachment point where the joint is fixed to the parent body.
+    child_point : Point
+        Attachment point where the joint is fixed to the child body.
+    parent_axis : Vector
+        The axis fixed in the parent frame that represents the joint.
+    child_axis : Vector
+        The axis fixed in the child frame that represents the joint.
+    parent_interframe : ReferenceFrame
+        Intermediate frame of the parent body with respect to which the joint
+        transformation is formulated.
+    child_interframe : ReferenceFrame
+        Intermediate frame of the child body with respect to which the joint
+        transformation is formulated.
+    kdes : Matrix
+        Kinematical differential equations of the joint.
+
+    Notes
+    =====
+
+    When providing a vector as the intermediate frame, a new intermediate frame
+    is created which aligns its X axis with the provided vector. This is done
+    with a single fixed rotation about a rotation axis. This rotation axis is
+    determined by taking the cross product of the ``body.x`` axis with the
+    provided vector. In the case where the provided vector is in the ``-body.x``
+    direction, the rotation is done about the ``body.y`` axis.
+
+    """
+
+    def __init__(self, name, parent, child, coordinates=None, speeds=None,
+                 parent_point=None, child_point=None, parent_interframe=None,
+                 child_interframe=None, parent_axis=None, child_axis=None,
+                 parent_joint_pos=None, child_joint_pos=None):
+
+        if not isinstance(name, str):
+            raise TypeError('Supply a valid name.')
+        self._name = name
+
+        if not isinstance(parent, BodyBase):
+            raise TypeError('Parent must be a body.')
+        self._parent = parent
+
+        if not isinstance(child, BodyBase):
+            raise TypeError('Child must be a body.')
+        self._child = child
+
+        if parent_axis is not None or child_axis is not None:
+            sympy_deprecation_warning(
+                """
+                The parent_axis and child_axis arguments for the Joint classes
+                are deprecated. Instead use parent_interframe, child_interframe.
+                """,
+                deprecated_since_version="1.12",
+                active_deprecations_target="deprecated-mechanics-joint-axis",
+                stacklevel=4
+            )
+            if parent_interframe is None:
+                parent_interframe = parent_axis
+            if child_interframe is None:
+                child_interframe = child_axis
+
+        # Set parent and child frame attributes
+        if hasattr(self._parent, 'frame'):
+            self._parent_frame = self._parent.frame
+        else:
+            if isinstance(parent_interframe, ReferenceFrame):
+                self._parent_frame = parent_interframe
+            else:
+                self._parent_frame = ReferenceFrame(
+                    f'{self.name}_{self._parent.name}_frame')
+        if hasattr(self._child, 'frame'):
+            self._child_frame = self._child.frame
+        else:
+            if isinstance(child_interframe, ReferenceFrame):
+                self._child_frame = child_interframe
+            else:
+                self._child_frame = ReferenceFrame(
+                    f'{self.name}_{self._child.name}_frame')
+
+        self._parent_interframe = self._locate_joint_frame(
+            self._parent, parent_interframe, self._parent_frame)
+        self._child_interframe = self._locate_joint_frame(
+            self._child, child_interframe, self._child_frame)
+        self._parent_axis = self._axis(parent_axis, self._parent_frame)
+        self._child_axis = self._axis(child_axis, self._child_frame)
+
+        if parent_joint_pos is not None or child_joint_pos is not None:
+            sympy_deprecation_warning(
+                """
+                The parent_joint_pos and child_joint_pos arguments for the Joint
+                classes are deprecated. Instead use parent_point and child_point.
+                """,
+                deprecated_since_version="1.12",
+                active_deprecations_target="deprecated-mechanics-joint-pos",
+                stacklevel=4
+            )
+            if parent_point is None:
+                parent_point = parent_joint_pos
+            if child_point is None:
+                child_point = child_joint_pos
+        self._parent_point = self._locate_joint_pos(
+            self._parent, parent_point, self._parent_frame)
+        self._child_point = self._locate_joint_pos(
+            self._child, child_point, self._child_frame)
+
+        self._coordinates = self._generate_coordinates(coordinates)
+        self._speeds = self._generate_speeds(speeds)
+        _validate_coordinates(self.coordinates, self.speeds)
+        self._kdes = self._generate_kdes()
+
+        self._orient_frames()
+        self._set_angular_velocity()
+        self._set_linear_velocity()
+
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return self.__str__()
+
+    @property
+    def name(self):
+        """Name of the joint."""
+        return self._name
+
+    @property
+    def parent(self):
+        """Parent body of Joint."""
+        return self._parent
+
+    @property
+    def child(self):
+        """Child body of Joint."""
+        return self._child
+
+    @property
+    def coordinates(self):
+        """Matrix of the joint's generalized coordinates."""
+        return self._coordinates
+
+    @property
+    def speeds(self):
+        """Matrix of the joint's generalized speeds."""
+        return self._speeds
+
+    @property
+    def kdes(self):
+        """Kinematical differential equations of the joint."""
+        return self._kdes
+
+    @property
+    def parent_axis(self):
+        """The axis of parent frame."""
+        # Will be removed with `deprecated-mechanics-joint-axis`
+        return self._parent_axis
+
+    @property
+    def child_axis(self):
+        """The axis of child frame."""
+        # Will be removed with `deprecated-mechanics-joint-axis`
+        return self._child_axis
+
+    @property
+    def parent_point(self):
+        """Attachment point where the joint is fixed to the parent body."""
+        return self._parent_point
+
+    @property
+    def child_point(self):
+        """Attachment point where the joint is fixed to the child body."""
+        return self._child_point
+
+    @property
+    def parent_interframe(self):
+        return self._parent_interframe
+
+    @property
+    def child_interframe(self):
+        return self._child_interframe
+
+    @abstractmethod
+    def _generate_coordinates(self, coordinates):
+        """Generate Matrix of the joint's generalized coordinates."""
+        pass
+
+    @abstractmethod
+    def _generate_speeds(self, speeds):
+        """Generate Matrix of the joint's generalized speeds."""
+        pass
+
+    @abstractmethod
+    def _orient_frames(self):
+        """Orient frames as per the joint."""
+        pass
+
+    @abstractmethod
+    def _set_angular_velocity(self):
+        """Set angular velocity of the joint related frames."""
+        pass
+
+    @abstractmethod
+    def _set_linear_velocity(self):
+        """Set velocity of related points to the joint."""
+        pass
+
+    @staticmethod
+    def _to_vector(matrix, frame):
+        """Converts a matrix to a vector in the given frame."""
+        return Vector([(matrix, frame)])
+
+    @staticmethod
+    def _axis(ax, *frames):
+        """Check whether an axis is fixed in one of the frames."""
+        if ax is None:
+            ax = frames[0].x
+            return ax
+        if not isinstance(ax, Vector):
+            raise TypeError("Axis must be a Vector.")
+        ref_frame = None  # Find a body in which the axis can be expressed
+        for frame in frames:
+            try:
+                ax.to_matrix(frame)
+            except ValueError:
+                pass
+            else:
+                ref_frame = frame
+                break
+        if ref_frame is None:
+            raise ValueError("Axis cannot be expressed in one of the body's "
+                             "frames.")
+        if not ax.dt(ref_frame) == 0:
+            raise ValueError('Axis cannot be time-varying when viewed from the '
+                             'associated body.')
+        return ax
+
+    @staticmethod
+    def _choose_rotation_axis(frame, axis):
+        components = axis.to_matrix(frame)
+        x, y, z = components[0], components[1], components[2]
+
+        if x != 0:
+            if y != 0:
+                if z != 0:
+                    return cross(axis, frame.x)
+            if z != 0:
+                return frame.y
+            return frame.z
+        else:
+            if y != 0:
+                return frame.x
+            return frame.y
+
+    @staticmethod
+    def _create_aligned_interframe(frame, align_axis, frame_axis=None,
+                                   frame_name=None):
+        """
+        Returns an intermediate frame, where the ``frame_axis`` defined in
+        ``frame`` is aligned with ``axis``. By default this means that the X
+        axis will be aligned with ``axis``.
+
+        Parameters
+        ==========
+
+        frame : BodyBase or ReferenceFrame
+            The body or reference frame with respect to which the intermediate
+            frame is oriented.
+        align_axis : Vector
+            The vector with respect to which the intermediate frame will be
+            aligned.
+        frame_axis : Vector
+            The vector of the frame which should get aligned with ``axis``. The
+            default is the X axis of the frame.
+        frame_name : string
+            Name of the to be created intermediate frame. The default adds
+            "_int_frame" to the name of ``frame``.
+
+        Example
+        =======
+
+        An intermediate frame, where the X axis of the parent becomes aligned
+        with ``parent.y + parent.z`` can be created as follows:
+
+        >>> from sympy.physics.mechanics.joint import Joint
+        >>> from sympy.physics.mechanics import RigidBody
+        >>> parent = RigidBody('parent')
+        >>> parent_interframe = Joint._create_aligned_interframe(
+        ...     parent, parent.y + parent.z)
+        >>> parent_interframe
+        parent_int_frame
+        >>> parent.frame.dcm(parent_interframe)
+        Matrix([
+        [        0, -sqrt(2)/2, -sqrt(2)/2],
+        [sqrt(2)/2,        1/2,       -1/2],
+        [sqrt(2)/2,       -1/2,        1/2]])
+        >>> (parent.y + parent.z).express(parent_interframe)
+        sqrt(2)*parent_int_frame.x
+
+        Notes
+        =====
+
+        The direction cosine matrix between the given frame and intermediate
+        frame is formed using a simple rotation about an axis that is normal to
+        both ``align_axis`` and ``frame_axis``. In general, the normal axis is
+        formed by crossing the ``frame_axis`` with the ``align_axis``. The
+        exception is if the axes are parallel with opposite directions, in which
+        case the rotation vector is chosen using the rules in the following
+        table with the vectors expressed in the given frame:
+
+        .. list-table::
+           :header-rows: 1
+
+           * - ``align_axis``
+             - ``frame_axis``
+             - ``rotation_axis``
+           * - ``-x``
+             - ``x``
+             - ``z``
+           * - ``-y``
+             - ``y``
+             - ``x``
+           * - ``-z``
+             - ``z``
+             - ``y``
+           * - ``-x-y``
+             - ``x+y``
+             - ``z``
+           * - ``-y-z``
+             - ``y+z``
+             - ``x``
+           * - ``-x-z``
+             - ``x+z``
+             - ``y``
+           * - ``-x-y-z``
+             - ``x+y+z``
+             - ``(x+y+z) × x``
+
+        """
+        if isinstance(frame, BodyBase):
+            frame = frame.frame
+        if frame_axis is None:
+            frame_axis = frame.x
+        if frame_name is None:
+            if frame.name[-6:] == '_frame':
+                frame_name = f'{frame.name[:-6]}_int_frame'
+            else:
+                frame_name = f'{frame.name}_int_frame'
+        angle = frame_axis.angle_between(align_axis)
+        rotation_axis = cross(frame_axis, align_axis)
+        if rotation_axis == Vector(0) and angle == 0:
+            return frame
+        if angle == pi:
+            rotation_axis = Joint._choose_rotation_axis(frame, align_axis)
+
+        int_frame = ReferenceFrame(frame_name)
+        int_frame.orient_axis(frame, rotation_axis, angle)
+        int_frame.set_ang_vel(frame, 0 * rotation_axis)
+        return int_frame
+
+    def _generate_kdes(self):
+        """Generate kinematical differential equations."""
+        kdes = []
+        t = dynamicsymbols._t
+        for i in range(len(self.coordinates)):
+            kdes.append(-self.coordinates[i].diff(t) + self.speeds[i])
+        return Matrix(kdes)
+
+    def _locate_joint_pos(self, body, joint_pos, body_frame=None):
+        """Returns the attachment point of a body."""
+        if body_frame is None:
+            body_frame = body.frame
+        if joint_pos is None:
+            return body.masscenter
+        if not isinstance(joint_pos, (Point, Vector)):
+            raise TypeError('Attachment point must be a Point or Vector.')
+        if isinstance(joint_pos, Vector):
+            point_name = f'{self.name}_{body.name}_joint'
+            joint_pos = body.masscenter.locatenew(point_name, joint_pos)
+        if not joint_pos.pos_from(body.masscenter).dt(body_frame) == 0:
+            raise ValueError('Attachment point must be fixed to the associated '
+                             'body.')
+        return joint_pos
+
+    def _locate_joint_frame(self, body, interframe, body_frame=None):
+        """Returns the attachment frame of a body."""
+        if body_frame is None:
+            body_frame = body.frame
+        if interframe is None:
+            return body_frame
+        if isinstance(interframe, Vector):
+            interframe = Joint._create_aligned_interframe(
+                body_frame, interframe,
+                frame_name=f'{self.name}_{body.name}_int_frame')
+        elif not isinstance(interframe, ReferenceFrame):
+            raise TypeError('Interframe must be a ReferenceFrame.')
+        if not interframe.ang_vel_in(body_frame) == 0:
+            raise ValueError(f'Interframe {interframe} is not fixed to body '
+                             f'{body}.')
+        body.masscenter.set_vel(interframe, 0)  # Fixate interframe to body
+        return interframe
+
+    def _fill_coordinate_list(self, coordinates, n_coords, label='q', offset=0,
+                              number_single=False):
+        """Helper method for _generate_coordinates and _generate_speeds.
+
+        Parameters
+        ==========
+
+        coordinates : iterable
+            Iterable of coordinates or speeds that have been provided.
+        n_coords : Integer
+            Number of coordinates that should be returned.
+        label : String, optional
+            Coordinate type either 'q' (coordinates) or 'u' (speeds). The
+            Default is 'q'.
+        offset : Integer
+            Count offset when creating new dynamicsymbols. The default is 0.
+        number_single : Boolean
+            Boolean whether if n_coords == 1, number should still be used. The
+            default is False.
+
+        """
+
+        def create_symbol(number):
+            if n_coords == 1 and not number_single:
+                return dynamicsymbols(f'{label}_{self.name}')
+            return dynamicsymbols(f'{label}{number}_{self.name}')
+
+        name = 'generalized coordinate' if label == 'q' else 'generalized speed'
+        generated_coordinates = []
+        if coordinates is None:
+            coordinates = []
+        elif not iterable(coordinates):
+            coordinates = [coordinates]
+        if not (len(coordinates) == 0 or len(coordinates) == n_coords):
+            raise ValueError(f'Expected {n_coords} {name}s, instead got '
+                             f'{len(coordinates)} {name}s.')
+        # Supports more iterables, also Matrix
+        for i, coord in enumerate(coordinates):
+            if coord is None:
+                generated_coordinates.append(create_symbol(i + offset))
+            elif isinstance(coord, (AppliedUndef, Derivative)):
+                generated_coordinates.append(coord)
+            else:
+                raise TypeError(f'The {name} {coord} should have been a '
+                                f'dynamicsymbol.')
+        for i in range(len(coordinates) + offset, n_coords + offset):
+            generated_coordinates.append(create_symbol(i))
+        return Matrix(generated_coordinates)
+
+
+class PinJoint(Joint):
+    """Pin (Revolute) Joint.
+
+    .. raw:: html
+        :file: ../../../doc/src/modules/physics/mechanics/api/PinJoint.svg
+
+    Explanation
+    ===========
+
+    A pin joint is defined such that the joint rotation axis is fixed in both
+    the child and parent and the location of the joint is relative to the mass
+    center of each body. The child rotates an angle, θ, from the parent about
+    the rotation axis and has a simple angular speed, ω, relative to the
+    parent. The direction cosine matrix between the child interframe and
+    parent interframe is formed using a simple rotation about the joint axis.
+    The page on the joints framework gives a more detailed explanation of the
+    intermediate frames.
+
+    Parameters
+    ==========
+
+    name : string
+        A unique name for the joint.
+    parent : Particle or RigidBody or Body
+        The parent body of joint.
+    child : Particle or RigidBody or Body
+        The child body of joint.
+    coordinates : dynamicsymbol, optional
+        Generalized coordinates of the joint.
+    speeds : dynamicsymbol, optional
+        Generalized speeds of joint.
+    parent_point : Point or Vector, optional
+        Attachment point where the joint is fixed to the parent body. If a
+        vector is provided, then the attachment point is computed by adding the
+        vector to the body's mass center. The default value is the parent's mass
+        center.
+    child_point : Point or Vector, optional
+        Attachment point where the joint is fixed to the child body. If a
+        vector is provided, then the attachment point is computed by adding the
+        vector to the body's mass center. The default value is the child's mass
+        center.
+    parent_axis : Vector, optional
+        .. deprecated:: 1.12
+            Axis fixed in the parent body which aligns with an axis fixed in the
+            child body. The default is the x axis of parent's reference frame.
+            For more information on this deprecation, see
+            :ref:`deprecated-mechanics-joint-axis`.
+    child_axis : Vector, optional
+        .. deprecated:: 1.12
+            Axis fixed in the child body which aligns with an axis fixed in the
+            parent body. The default is the x axis of child's reference frame.
+            For more information on this deprecation, see
+            :ref:`deprecated-mechanics-joint-axis`.
+    parent_interframe : ReferenceFrame, optional
+        Intermediate frame of the parent body with respect to which the joint
+        transformation is formulated. If a Vector is provided then an interframe
+        is created which aligns its X axis with the given vector. The default
+        value is the parent's own frame.
+    child_interframe : ReferenceFrame, optional
+        Intermediate frame of the child body with respect to which the joint
+        transformation is formulated. If a Vector is provided then an interframe
+        is created which aligns its X axis with the given vector. The default
+        value is the child's own frame.
+    joint_axis : Vector
+        The axis about which the rotation occurs. Note that the components
+        of this axis are the same in the parent_interframe and child_interframe.
+    parent_joint_pos : Point or Vector, optional
+        .. deprecated:: 1.12
+            This argument is replaced by parent_point and will be removed in a
+            future version.
+            See :ref:`deprecated-mechanics-joint-pos` for more information.
+    child_joint_pos : Point or Vector, optional
+        .. deprecated:: 1.12
+            This argument is replaced by child_point and will be removed in a
+            future version.
+            See :ref:`deprecated-mechanics-joint-pos` for more information.
+
+    Attributes
+    ==========
+
+    name : string
+        The joint's name.
+    parent : Particle or RigidBody or Body
+        The joint's parent body.
+    child : Particle or RigidBody or Body
+        The joint's child body.
+    coordinates : Matrix
+        Matrix of the joint's generalized coordinates. The default value is
+        ``dynamicsymbols(f'q_{joint.name}')``.
+    speeds : Matrix
+        Matrix of the joint's generalized speeds. The default value is
+        ``dynamicsymbols(f'u_{joint.name}')``.
+    parent_point : Point
+        Attachment point where the joint is fixed to the parent body.
+    child_point : Point
+        Attachment point where the joint is fixed to the child body.
+    parent_axis : Vector
+        The axis fixed in the parent frame that represents the joint.
+    child_axis : Vector
+        The axis fixed in the child frame that represents the joint.
+    parent_interframe : ReferenceFrame
+        Intermediate frame of the parent body with respect to which the joint
+        transformation is formulated.
+    child_interframe : ReferenceFrame
+        Intermediate frame of the child body with respect to which the joint
+        transformation is formulated.
+    joint_axis : Vector
+        The axis about which the rotation occurs. Note that the components of
+        this axis are the same in the parent_interframe and child_interframe.
+    kdes : Matrix
+        Kinematical differential equations of the joint.
+
+    Examples
+    =========
+
+    A single pin joint is created from two bodies and has the following basic
+    attributes:
+
+    >>> from sympy.physics.mechanics import RigidBody, PinJoint
+    >>> parent = RigidBody('P')
+    >>> parent
+    P
+    >>> child = RigidBody('C')
+    >>> child
+    C
+    >>> joint = PinJoint('PC', parent, child)
+    >>> joint
+    PinJoint: PC  parent: P  child: C
+    >>> joint.name
+    'PC'
+    >>> joint.parent
+    P
+    >>> joint.child
+    C
+    >>> joint.parent_point
+    P_masscenter
+    >>> joint.child_point
+    C_masscenter
+    >>> joint.parent_axis
+    P_frame.x
+    >>> joint.child_axis
+    C_frame.x
+    >>> joint.coordinates
+    Matrix([[q_PC(t)]])
+    >>> joint.speeds
+    Matrix([[u_PC(t)]])
+    >>> child.frame.ang_vel_in(parent.frame)
+    u_PC(t)*P_frame.x
+    >>> child.frame.dcm(parent.frame)
+    Matrix([
+    [1,             0,            0],
+    [0,  cos(q_PC(t)), sin(q_PC(t))],
+    [0, -sin(q_PC(t)), cos(q_PC(t))]])
+    >>> joint.child_point.pos_from(joint.parent_point)
+    0
+
+    To further demonstrate the use of the pin joint, the kinematics of simple
+    double pendulum that rotates about the Z axis of each connected body can be
+    created as follows.
+
+    >>> from sympy import symbols, trigsimp
+    >>> from sympy.physics.mechanics import RigidBody, PinJoint
+    >>> l1, l2 = symbols('l1 l2')
+
+    First create bodies to represent the fixed ceiling and one to represent
+    each pendulum bob.
+
+    >>> ceiling = RigidBody('C')
+    >>> upper_bob = RigidBody('U')
+    >>> lower_bob = RigidBody('L')
+
+    The first joint will connect the upper bob to the ceiling by a distance of
+    ``l1`` and the joint axis will be about the Z axis for each body.
+
+    >>> ceiling_joint = PinJoint('P1', ceiling, upper_bob,
+    ... child_point=-l1*upper_bob.frame.x,
+    ... joint_axis=ceiling.frame.z)
+
+    The second joint will connect the lower bob to the upper bob by a distance
+    of ``l2`` and the joint axis will also be about the Z axis for each body.
+
+    >>> pendulum_joint = PinJoint('P2', upper_bob, lower_bob,
+    ... child_point=-l2*lower_bob.frame.x,
+    ... joint_axis=upper_bob.frame.z)
+
+    Once the joints are established the kinematics of the connected bodies can
+    be accessed. First the direction cosine matrices of pendulum link relative
+    to the ceiling are found:
+
+    >>> upper_bob.frame.dcm(ceiling.frame)
+    Matrix([
+    [ cos(q_P1(t)), sin(q_P1(t)), 0],
+    [-sin(q_P1(t)), cos(q_P1(t)), 0],
+    [            0,            0, 1]])
+    >>> trigsimp(lower_bob.frame.dcm(ceiling.frame))
+    Matrix([
+    [ cos(q_P1(t) + q_P2(t)), sin(q_P1(t) + q_P2(t)), 0],
+    [-sin(q_P1(t) + q_P2(t)), cos(q_P1(t) + q_P2(t)), 0],
+    [                      0,                      0, 1]])
+
+    The position of the lower bob's masscenter is found with:
+
+    >>> lower_bob.masscenter.pos_from(ceiling.masscenter)
+    l1*U_frame.x + l2*L_frame.x
+
+    The angular velocities of the two pendulum links can be computed with
+    respect to the ceiling.
+
+    >>> upper_bob.frame.ang_vel_in(ceiling.frame)
+    u_P1(t)*C_frame.z
+    >>> lower_bob.frame.ang_vel_in(ceiling.frame)
+    u_P1(t)*C_frame.z + u_P2(t)*U_frame.z
+
+    And finally, the linear velocities of the two pendulum bobs can be computed
+    with respect to the ceiling.
+
+    >>> upper_bob.masscenter.vel(ceiling.frame)
+    l1*u_P1(t)*U_frame.y
+    >>> lower_bob.masscenter.vel(ceiling.frame)
+    l1*u_P1(t)*U_frame.y + l2*(u_P1(t) + u_P2(t))*L_frame.y
+
+    """
+
+    def __init__(self, name, parent, child, coordinates=None, speeds=None,
+                 parent_point=None, child_point=None, parent_interframe=None,
+                 child_interframe=None, parent_axis=None, child_axis=None,
+                 joint_axis=None, parent_joint_pos=None, child_joint_pos=None):
+
+        self._joint_axis = joint_axis
+        super().__init__(name, parent, child, coordinates, speeds, parent_point,
+                         child_point, parent_interframe, child_interframe,
+                         parent_axis, child_axis, parent_joint_pos,
+                         child_joint_pos)
+
+    def __str__(self):
+        return (f'PinJoint: {self.name}  parent: {self.parent}  '
+                f'child: {self.child}')
+
+    @property
+    def joint_axis(self):
+        """Axis about which the child rotates with respect to the parent."""
+        return self._joint_axis
+
+    def _generate_coordinates(self, coordinate):
+        return self._fill_coordinate_list(coordinate, 1, 'q')
+
+    def _generate_speeds(self, speed):
+        return self._fill_coordinate_list(speed, 1, 'u')
+
+    def _orient_frames(self):
+        self._joint_axis = self._axis(self.joint_axis, self.parent_interframe)
+        self.child_interframe.orient_axis(
+            self.parent_interframe, self.joint_axis, self.coordinates[0])
+
+    def _set_angular_velocity(self):
+        self.child_interframe.set_ang_vel(self.parent_interframe, self.speeds[
+            0] * self.joint_axis.normalize())
+
+    def _set_linear_velocity(self):
+        self.child_point.set_pos(self.parent_point, 0)
+        self.parent_point.set_vel(self._parent_frame, 0)
+        self.child_point.set_vel(self._child_frame, 0)
+        self.child.masscenter.v2pt_theory(self.parent_point,
+                                          self._parent_frame, self._child_frame)
+
+
+class PrismaticJoint(Joint):
+    """Prismatic (Sliding) Joint.
+
+    .. image:: PrismaticJoint.svg
+
+    Explanation
+    ===========
+
+    It is defined such that the child body translates with respect to the parent
+    body along the body-fixed joint axis. The location of the joint is defined
+    by two points, one in each body, which coincide when the generalized
+    coordinate is zero. The direction cosine matrix between the
+    parent_interframe and child_interframe is the identity matrix. Therefore,
+    the direction cosine matrix between the parent and child frames is fully
+    defined by the definition of the intermediate frames. The page on the joints
+    framework gives a more detailed explanation of the intermediate frames.
+
+    Parameters
+    ==========
+
+    name : string
+        A unique name for the joint.
+    parent : Particle or RigidBody or Body
+        The parent body of joint.
+    child : Particle or RigidBody or Body
+        The child body of joint.
+    coordinates : dynamicsymbol, optional
+        Generalized coordinates of the joint. The default value is
+        ``dynamicsymbols(f'q_{joint.name}')``.
+    speeds : dynamicsymbol, optional
+        Generalized speeds of joint. The default value is
+        ``dynamicsymbols(f'u_{joint.name}')``.
+    parent_point : Point or Vector, optional
+        Attachment point where the joint is fixed to the parent body. If a
+        vector is provided, then the attachment point is computed by adding the
+        vector to the body's mass center. The default value is the parent's mass
+        center.
+    child_point : Point or Vector, optional
+        Attachment point where the joint is fixed to the child body. If a
+        vector is provided, then the attachment point is computed by adding the
+        vector to the body's mass center. The default value is the child's mass
+        center.
+    parent_axis : Vector, optional
+        .. deprecated:: 1.12
+            Axis fixed in the parent body which aligns with an axis fixed in the
+            child body. The default is the x axis of parent's reference frame.
+            For more information on this deprecation, see
+            :ref:`deprecated-mechanics-joint-axis`.
+    child_axis : Vector, optional
+        .. deprecated:: 1.12
+            Axis fixed in the child body which aligns with an axis fixed in the
+            parent body. The default is the x axis of child's reference frame.
+            For more information on this deprecation, see
+            :ref:`deprecated-mechanics-joint-axis`.
+    parent_interframe : ReferenceFrame, optional
+        Intermediate frame of the parent body with respect to which the joint
+        transformation is formulated. If a Vector is provided then an interframe
+        is created which aligns its X axis with the given vector. The default
+        value is the parent's own frame.
+    child_interframe : ReferenceFrame, optional
+        Intermediate frame of the child body with respect to which the joint
+        transformation is formulated. If a Vector is provided then an interframe
+        is created which aligns its X axis with the given vector. The default
+        value is the child's own frame.
+    joint_axis : Vector
+        The axis along which the translation occurs. Note that the components
+        of this axis are the same in the parent_interframe and child_interframe.
+    parent_joint_pos : Point or Vector, optional
+        .. deprecated:: 1.12
+            This argument is replaced by parent_point and will be removed in a
+            future version.
+            See :ref:`deprecated-mechanics-joint-pos` for more information.
+    child_joint_pos : Point or Vector, optional
+        .. deprecated:: 1.12
+            This argument is replaced by child_point and will be removed in a
+            future version.
+            See :ref:`deprecated-mechanics-joint-pos` for more information.
+
+    Attributes
+    ==========
+
+    name : string
+        The joint's name.
+    parent : Particle or RigidBody or Body
+        The joint's parent body.
+    child : Particle or RigidBody or Body
+        The joint's child body.
+    coordinates : Matrix
+        Matrix of the joint's generalized coordinates.
+    speeds : Matrix
+        Matrix of the joint's generalized speeds.
+    parent_point : Point
+        Attachment point where the joint is fixed to the parent body.
+    child_point : Point
+        Attachment point where the joint is fixed to the child body.
+    parent_axis : Vector
+        The axis fixed in the parent frame that represents the joint.
+    child_axis : Vector
+        The axis fixed in the child frame that represents the joint.
+    parent_interframe : ReferenceFrame
+        Intermediate frame of the parent body with respect to which the joint
+        transformation is formulated.
+    child_interframe : ReferenceFrame
+        Intermediate frame of the child body with respect to which the joint
+        transformation is formulated.
+    kdes : Matrix
+        Kinematical differential equations of the joint.
+
+    Examples
+    =========
+
+    A single prismatic joint is created from two bodies and has the following
+    basic attributes:
+
+    >>> from sympy.physics.mechanics import RigidBody, PrismaticJoint
+    >>> parent = RigidBody('P')
+    >>> parent
+    P
+    >>> child = RigidBody('C')
+    >>> child
+    C
+    >>> joint = PrismaticJoint('PC', parent, child)
+    >>> joint
+    PrismaticJoint: PC  parent: P  child: C
+    >>> joint.name
+    'PC'
+    >>> joint.parent
+    P
+    >>> joint.child
+    C
+    >>> joint.parent_point
+    P_masscenter
+    >>> joint.child_point
+    C_masscenter
+    >>> joint.parent_axis
+    P_frame.x
+    >>> joint.child_axis
+    C_frame.x
+    >>> joint.coordinates
+    Matrix([[q_PC(t)]])
+    >>> joint.speeds
+    Matrix([[u_PC(t)]])
+    >>> child.frame.ang_vel_in(parent.frame)
+    0
+    >>> child.frame.dcm(parent.frame)
+    Matrix([
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1]])
+    >>> joint.child_point.pos_from(joint.parent_point)
+    q_PC(t)*P_frame.x
+
+    To further demonstrate the use of the prismatic joint, the kinematics of two
+    masses sliding, one moving relative to a fixed body and the other relative
+    to the moving body. about the X axis of each connected body can be created
+    as follows.
+
+    >>> from sympy.physics.mechanics import PrismaticJoint, RigidBody
+
+    First create bodies to represent the fixed ceiling and one to represent
+    a particle.
+
+    >>> wall = RigidBody('W')
+    >>> Part1 = RigidBody('P1')
+    >>> Part2 = RigidBody('P2')
+
+    The first joint will connect the particle to the ceiling and the
+    joint axis will be about the X axis for each body.
+
+    >>> J1 = PrismaticJoint('J1', wall, Part1)
+
+    The second joint will connect the second particle to the first particle
+    and the joint axis will also be about the X axis for each body.
+
+    >>> J2 = PrismaticJoint('J2', Part1, Part2)
+
+    Once the joint is established the kinematics of the connected bodies can
+    be accessed. First the direction cosine matrices of Part relative
+    to the ceiling are found:
+
+    >>> Part1.frame.dcm(wall.frame)
+    Matrix([
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1]])
+
+    >>> Part2.frame.dcm(wall.frame)
+    Matrix([
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1]])
+
+    The position of the particles' masscenter is found with:
+
+    >>> Part1.masscenter.pos_from(wall.masscenter)
+    q_J1(t)*W_frame.x
+
+    >>> Part2.masscenter.pos_from(wall.masscenter)
+    q_J1(t)*W_frame.x + q_J2(t)*P1_frame.x
+
+    The angular velocities of the two particle links can be computed with
+    respect to the ceiling.
+
+    >>> Part1.frame.ang_vel_in(wall.frame)
+    0
+
+    >>> Part2.frame.ang_vel_in(wall.frame)
+    0
+
+    And finally, the linear velocities of the two particles can be computed
+    with respect to the ceiling.
+
+    >>> Part1.masscenter.vel(wall.frame)
+    u_J1(t)*W_frame.x
+
+    >>> Part2.masscenter.vel(wall.frame)
+    u_J1(t)*W_frame.x + Derivative(q_J2(t), t)*P1_frame.x
+
+    """
+
+    def __init__(self, name, parent, child, coordinates=None, speeds=None,
+                 parent_point=None, child_point=None, parent_interframe=None,
+                 child_interframe=None, parent_axis=None, child_axis=None,
+                 joint_axis=None, parent_joint_pos=None, child_joint_pos=None):
+
+        self._joint_axis = joint_axis
+        super().__init__(name, parent, child, coordinates, speeds, parent_point,
+                         child_point, parent_interframe, child_interframe,
+                         parent_axis, child_axis, parent_joint_pos,
+                         child_joint_pos)
+
+    def __str__(self):
+        return (f'PrismaticJoint: {self.name}  parent: {self.parent}  '
+                f'child: {self.child}')
+
+    @property
+    def joint_axis(self):
+        """Axis along which the child translates with respect to the parent."""
+        return self._joint_axis
+
+    def _generate_coordinates(self, coordinate):
+        return self._fill_coordinate_list(coordinate, 1, 'q')
+
+    def _generate_speeds(self, speed):
+        return self._fill_coordinate_list(speed, 1, 'u')
+
+    def _orient_frames(self):
+        self._joint_axis = self._axis(self.joint_axis, self.parent_interframe)
+        self.child_interframe.orient_axis(
+            self.parent_interframe, self.joint_axis, 0)
+
+    def _set_angular_velocity(self):
+        self.child_interframe.set_ang_vel(self.parent_interframe, 0)
+
+    def _set_linear_velocity(self):
+        axis = self.joint_axis.normalize()
+        self.child_point.set_pos(self.parent_point, self.coordinates[0] * axis)
+        self.parent_point.set_vel(self._parent_frame, 0)
+        self.child_point.set_vel(self._child_frame, 0)
+        self.child_point.set_vel(self._parent_frame, self.speeds[0] * axis)
+        self.child.masscenter.set_vel(self._parent_frame, self.speeds[0] * axis)
+
+
+class CylindricalJoint(Joint):
+    """Cylindrical Joint.
+
+    .. image:: CylindricalJoint.svg
+        :align: center
+        :width: 600
+
+    Explanation
+    ===========
+
+    A cylindrical joint is defined such that the child body both rotates about
+    and translates along the body-fixed joint axis with respect to the parent
+    body. The joint axis is both the rotation axis and translation axis. The
+    location of the joint is defined by two points, one in each body, which
+    coincide when the generalized coordinate corresponding to the translation is
+    zero. The direction cosine matrix between the child interframe and parent
+    interframe is formed using a simple rotation about the joint axis. The page
+    on the joints framework gives a more detailed explanation of the
+    intermediate frames.
+
+    Parameters
+    ==========
+
+    name : string
+        A unique name for the joint.
+    parent : Particle or RigidBody or Body
+        The parent body of joint.
+    child : Particle or RigidBody or Body
+        The child body of joint.
+    rotation_coordinate : dynamicsymbol, optional
+        Generalized coordinate corresponding to the rotation angle. The default
+        value is ``dynamicsymbols(f'q0_{joint.name}')``.
+    translation_coordinate : dynamicsymbol, optional
+        Generalized coordinate corresponding to the translation distance. The
+        default value is ``dynamicsymbols(f'q1_{joint.name}')``.
+    rotation_speed : dynamicsymbol, optional
+        Generalized speed corresponding to the angular velocity. The default
+        value is ``dynamicsymbols(f'u0_{joint.name}')``.
+    translation_speed : dynamicsymbol, optional
+        Generalized speed corresponding to the translation velocity. The default
+        value is ``dynamicsymbols(f'u1_{joint.name}')``.
+    parent_point : Point or Vector, optional
+        Attachment point where the joint is fixed to the parent body. If a
+        vector is provided, then the attachment point is computed by adding the
+        vector to the body's mass center. The default value is the parent's mass
+        center.
+    child_point : Point or Vector, optional
+        Attachment point where the joint is fixed to the child body. If a
+        vector is provided, then the attachment point is computed by adding the
+        vector to the body's mass center. The default value is the child's mass
+        center.
+    parent_interframe : ReferenceFrame, optional
+        Intermediate frame of the parent body with respect to which the joint
+        transformation is formulated. If a Vector is provided then an interframe
+        is created which aligns its X axis with the given vector. The default
+        value is the parent's own frame.
+    child_interframe : ReferenceFrame, optional
+        Intermediate frame of the child body with respect to which the joint
+        transformation is formulated. If a Vector is provided then an interframe
+        is created which aligns its X axis with the given vector. The default
+        value is the child's own frame.
+    joint_axis : Vector, optional
+        The rotation as well as translation axis. Note that the components of
+        this axis are the same in the parent_interframe and child_interframe.
+
+    Attributes
+    ==========
+
+    name : string
+        The joint's name.
+    parent : Particle or RigidBody or Body
+        The joint's parent body.
+    child : Particle or RigidBody or Body
+        The joint's child body.
+    rotation_coordinate : dynamicsymbol
+        Generalized coordinate corresponding to the rotation angle.
+    translation_coordinate : dynamicsymbol
+        Generalized coordinate corresponding to the translation distance.
+    rotation_speed : dynamicsymbol
+        Generalized speed corresponding to the angular velocity.
+    translation_speed : dynamicsymbol
+        Generalized speed corresponding to the translation velocity.
+    coordinates : Matrix
+        Matrix of the joint's generalized coordinates.
+    speeds : Matrix
+        Matrix of the joint's generalized speeds.
+    parent_point : Point
+        Attachment point where the joint is fixed to the parent body.
+    child_point : Point
+        Attachment point where the joint is fixed to the child body.
+    parent_interframe : ReferenceFrame
+        Intermediate frame of the parent body with respect to which the joint
+        transformation is formulated.
+    child_interframe : ReferenceFrame
+        Intermediate frame of the child body with respect to which the joint
+        transformation is formulated.
+    kdes : Matrix
+        Kinematical differential equations of the joint.
+    joint_axis : Vector
+        The axis of rotation and translation.
+
+    Examples
+    =========
+
+    A single cylindrical joint is created between two bodies and has the
+    following basic attributes:
+
+    >>> from sympy.physics.mechanics import RigidBody, CylindricalJoint
+    >>> parent = RigidBody('P')
+    >>> parent
+    P
+    >>> child = RigidBody('C')
+    >>> child
+    C
+    >>> joint = CylindricalJoint('PC', parent, child)
+    >>> joint
+    CylindricalJoint: PC  parent: P  child: C
+    >>> joint.name
+    'PC'
+    >>> joint.parent
+    P
+    >>> joint.child
+    C
+    >>> joint.parent_point
+    P_masscenter
+    >>> joint.child_point
+    C_masscenter
+    >>> joint.parent_axis
+    P_frame.x
+    >>> joint.child_axis
+    C_frame.x
+    >>> joint.coordinates
+    Matrix([
+    [q0_PC(t)],
+    [q1_PC(t)]])
+    >>> joint.speeds
+    Matrix([
+    [u0_PC(t)],
+    [u1_PC(t)]])
+    >>> child.frame.ang_vel_in(parent.frame)
+    u0_PC(t)*P_frame.x
+    >>> child.frame.dcm(parent.frame)
+    Matrix([
+    [1,              0,             0],
+    [0,  cos(q0_PC(t)), sin(q0_PC(t))],
+    [0, -sin(q0_PC(t)), cos(q0_PC(t))]])
+    >>> joint.child_point.pos_from(joint.parent_point)
+    q1_PC(t)*P_frame.x
+    >>> child.masscenter.vel(parent.frame)
+    u1_PC(t)*P_frame.x
+
+    To further demonstrate the use of the cylindrical joint, the kinematics of
+    two cylindrical joints perpendicular to each other can be created as follows.
+
+    >>> from sympy import symbols
+    >>> from sympy.physics.mechanics import RigidBody, CylindricalJoint
+    >>> r, l, w = symbols('r l w')
+
+    First create bodies to represent the fixed floor with a fixed pole on it.
+    The second body represents a freely moving tube around that pole. The third
+    body represents a solid flag freely translating along and rotating around
+    the Y axis of the tube.
+
+    >>> floor = RigidBody('floor')
+    >>> tube = RigidBody('tube')
+    >>> flag = RigidBody('flag')
+
+    The first joint will connect the first tube to the floor with it translating
+    along and rotating around the Z axis of both bodies.
+
+    >>> floor_joint = CylindricalJoint('C1', floor, tube, joint_axis=floor.z)
+
+    The second joint will connect the tube perpendicular to the flag along the Y
+    axis of both the tube and the flag, with the joint located at a distance
+    ``r`` from the tube's center of mass and a combination of the distances
+    ``l`` and ``w`` from the flag's center of mass.
+
+    >>> flag_joint = CylindricalJoint('C2', tube, flag,
+    ...                               parent_point=r * tube.y,
+    ...                               child_point=-w * flag.y + l * flag.z,
+    ...                               joint_axis=tube.y)
+
+    Once the joints are established the kinematics of the connected bodies can
+    be accessed. First the direction cosine matrices of both the body and the
+    flag relative to the floor are found:
+
+    >>> tube.frame.dcm(floor.frame)
+    Matrix([
+    [ cos(q0_C1(t)), sin(q0_C1(t)), 0],
+    [-sin(q0_C1(t)), cos(q0_C1(t)), 0],
+    [             0,             0, 1]])
+    >>> flag.frame.dcm(floor.frame)
+    Matrix([
+    [cos(q0_C1(t))*cos(q0_C2(t)), sin(q0_C1(t))*cos(q0_C2(t)), -sin(q0_C2(t))],
+    [             -sin(q0_C1(t)),               cos(q0_C1(t)),              0],
+    [sin(q0_C2(t))*cos(q0_C1(t)), sin(q0_C1(t))*sin(q0_C2(t)),  cos(q0_C2(t))]])
+
+    The position of the flag's center of mass is found with:
+
+    >>> flag.masscenter.pos_from(floor.masscenter)
+    q1_C1(t)*floor_frame.z + (r + q1_C2(t))*tube_frame.y + w*flag_frame.y - l*flag_frame.z
+
+    The angular velocities of the two tubes can be computed with respect to the
+    floor.
+
+    >>> tube.frame.ang_vel_in(floor.frame)
+    u0_C1(t)*floor_frame.z
+    >>> flag.frame.ang_vel_in(floor.frame)
+    u0_C1(t)*floor_frame.z + u0_C2(t)*tube_frame.y
+
+    Finally, the linear velocities of the two tube centers of mass can be
+    computed with respect to the floor, while expressed in the tube's frame.
+
+    >>> tube.masscenter.vel(floor.frame).to_matrix(tube.frame)
+    Matrix([
+    [       0],
+    [       0],
+    [u1_C1(t)]])
+    >>> flag.masscenter.vel(floor.frame).to_matrix(tube.frame).simplify()
+    Matrix([
+    [-l*u0_C2(t)*cos(q0_C2(t)) - r*u0_C1(t) - w*u0_C1(t) - q1_C2(t)*u0_C1(t)],
+    [                    -l*u0_C1(t)*sin(q0_C2(t)) + Derivative(q1_C2(t), t)],
+    [                                    l*u0_C2(t)*sin(q0_C2(t)) + u1_C1(t)]])
+
+    """
+
+    def __init__(self, name, parent, child, rotation_coordinate=None,
+                 translation_coordinate=None, rotation_speed=None,
+                 translation_speed=None, parent_point=None, child_point=None,
+                 parent_interframe=None, child_interframe=None,
+                 joint_axis=None):
+        self._joint_axis = joint_axis
+        coordinates = (rotation_coordinate, translation_coordinate)
+        speeds = (rotation_speed, translation_speed)
+        super().__init__(name, parent, child, coordinates, speeds,
+                         parent_point, child_point,
+                         parent_interframe=parent_interframe,
+                         child_interframe=child_interframe)
+
+    def __str__(self):
+        return (f'CylindricalJoint: {self.name}  parent: {self.parent}  '
+                f'child: {self.child}')
+
+    @property
+    def joint_axis(self):
+        """Axis about and along which the rotation and translation occurs."""
+        return self._joint_axis
+
+    @property
+    def rotation_coordinate(self):
+        """Generalized coordinate corresponding to the rotation angle."""
+        return self.coordinates[0]
+
+    @property
+    def translation_coordinate(self):
+        """Generalized coordinate corresponding to the translation distance."""
+        return self.coordinates[1]
+
+    @property
+    def rotation_speed(self):
+        """Generalized speed corresponding to the angular velocity."""
+        return self.speeds[0]
+
+    @property
+    def translation_speed(self):
+        """Generalized speed corresponding to the translation velocity."""
+        return self.speeds[1]
+
+    def _generate_coordinates(self, coordinates):
+        return self._fill_coordinate_list(coordinates, 2, 'q')
+
+    def _generate_speeds(self, speeds):
+        return self._fill_coordinate_list(speeds, 2, 'u')
+
+    def _orient_frames(self):
+        self._joint_axis = self._axis(self.joint_axis, self.parent_interframe)
+        self.child_interframe.orient_axis(
+            self.parent_interframe, self.joint_axis, self.rotation_coordinate)
+
+    def _set_angular_velocity(self):
+        self.child_interframe.set_ang_vel(
+            self.parent_interframe,
+            self.rotation_speed * self.joint_axis.normalize())
+
+    def _set_linear_velocity(self):
+        self.child_point.set_pos(
+            self.parent_point,
+            self.translation_coordinate * self.joint_axis.normalize())
+        self.parent_point.set_vel(self._parent_frame, 0)
+        self.child_point.set_vel(self._child_frame, 0)
+        self.child_point.set_vel(
+            self._parent_frame,
+            self.translation_speed * self.joint_axis.normalize())
+        self.child.masscenter.v2pt_theory(self.child_point, self._parent_frame,
+                                          self.child_interframe)
+
+
+class PlanarJoint(Joint):
+    """Planar Joint.
+
+    .. raw:: html
+        :file: ../../../doc/src/modules/physics/mechanics/api/PlanarJoint.svg
+
+    Explanation
+    ===========
+
+    A planar joint is defined such that the child body translates over a fixed
+    plane of the parent body as well as rotate about the rotation axis, which
+    is perpendicular to that plane. The origin of this plane is the
+    ``parent_point`` and the plane is spanned by two nonparallel planar vectors.
+    The location of the ``child_point`` is based on the planar vectors
+    ($\\vec{v}_1$, $\\vec{v}_2$) and generalized coordinates ($q_1$, $q_2$),
+    i.e. $\\vec{r} = q_1 \\hat{v}_1 + q_2 \\hat{v}_2$. The direction cosine
+    matrix between the ``child_interframe`` and ``parent_interframe`` is formed
+    using a simple rotation ($q_0$) about the rotation axis.
+
+    In order to simplify the definition of the ``PlanarJoint``, the
+    ``rotation_axis`` and ``planar_vectors`` are set to be the unit vectors of
+    the ``parent_interframe`` according to the table below. This ensures that
+    you can only define these vectors by creating a separate frame and supplying
+    that as the interframe. If you however would only like to supply the normals
+    of the plane with respect to the parent and child bodies, then you can also
+    supply those to the ``parent_interframe`` and ``child_interframe``
+    arguments. An example of both of these cases is in the examples section
+    below and the page on the joints framework provides a more detailed
+    explanation of the intermediate frames.
+
+    .. list-table::
+
+        * - ``rotation_axis``
+          - ``parent_interframe.x``
+        * - ``planar_vectors[0]``
+          - ``parent_interframe.y``
+        * - ``planar_vectors[1]``
+          - ``parent_interframe.z``
+
+    Parameters
+    ==========
+
+    name : string
+        A unique name for the joint.
+    parent : Particle or RigidBody or Body
+        The parent body of joint.
+    child : Particle or RigidBody or Body
+        The child body of joint.
+    rotation_coordinate : dynamicsymbol, optional
+        Generalized coordinate corresponding to the rotation angle. The default
+        value is ``dynamicsymbols(f'q0_{joint.name}')``.
+    planar_coordinates : iterable of dynamicsymbols, optional
+        Two generalized coordinates used for the planar translation. The default
+        value is ``dynamicsymbols(f'q1_{joint.name} q2_{joint.name}')``.
+    rotation_speed : dynamicsymbol, optional
+        Generalized speed corresponding to the angular velocity. The default
+        value is ``dynamicsymbols(f'u0_{joint.name}')``.
+    planar_speeds : dynamicsymbols, optional
+        Two generalized speeds used for the planar translation velocity. The
+        default value is ``dynamicsymbols(f'u1_{joint.name} u2_{joint.name}')``.
+    parent_point : Point or Vector, optional
+        Attachment point where the joint is fixed to the parent body. If a
+        vector is provided, then the attachment point is computed by adding the
+        vector to the body's mass center. The default value is the parent's mass
+        center.
+    child_point : Point or Vector, optional
+        Attachment point where the joint is fixed to the child body. If a
+        vector is provided, then the attachment point is computed by adding the
+        vector to the body's mass center. The default value is the child's mass
+        center.
+    parent_interframe : ReferenceFrame, optional
+        Intermediate frame of the parent body with respect to which the joint
+        transformation is formulated. If a Vector is provided then an interframe
+        is created which aligns its X axis with the given vector. The default
+        value is the parent's own frame.
+    child_interframe : ReferenceFrame, optional
+        Intermediate frame of the child body with respect to which the joint
+        transformation is formulated. If a Vector is provided then an interframe
+        is created which aligns its X axis with the given vector. The default
+        value is the child's own frame.
+
+    Attributes
+    ==========
+
+    name : string
+        The joint's name.
+    parent : Particle or RigidBody or Body
+        The joint's parent body.
+    child : Particle or RigidBody or Body
+        The joint's child body.
+    rotation_coordinate : dynamicsymbol
+        Generalized coordinate corresponding to the rotation angle.
+    planar_coordinates : Matrix
+        Two generalized coordinates used for the planar translation.
+    rotation_speed : dynamicsymbol
+        Generalized speed corresponding to the angular velocity.
+    planar_speeds : Matrix
+        Two generalized speeds used for the planar translation velocity.
+    coordinates : Matrix
+        Matrix of the joint's generalized coordinates.
+    speeds : Matrix
+        Matrix of the joint's generalized speeds.
+    parent_point : Point
+        Attachment point where the joint is fixed to the parent body.
+    child_point : Point
+        Attachment point where the joint is fixed to the child body.
+    parent_interframe : ReferenceFrame
+        Intermediate frame of the parent body with respect to which the joint
+        transformation is formulated.
+    child_interframe : ReferenceFrame
+        Intermediate frame of the child body with respect to which the joint
+        transformation is formulated.
+    kdes : Matrix
+        Kinematical differential equations of the joint.
+    rotation_axis : Vector
+        The axis about which the rotation occurs.
+    planar_vectors : list
+        The vectors that describe the planar translation directions.
+
+    Examples
+    =========
+
+    A single planar joint is created between two bodies and has the following
+    basic attributes:
+
+    >>> from sympy.physics.mechanics import RigidBody, PlanarJoint
+    >>> parent = RigidBody('P')
+    >>> parent
+    P
+    >>> child = RigidBody('C')
+    >>> child
+    C
+    >>> joint = PlanarJoint('PC', parent, child)
+    >>> joint
+    PlanarJoint: PC  parent: P  child: C
+    >>> joint.name
+    'PC'
+    >>> joint.parent
+    P
+    >>> joint.child
+    C
+    >>> joint.parent_point
+    P_masscenter
+    >>> joint.child_point
+    C_masscenter
+    >>> joint.rotation_axis
+    P_frame.x
+    >>> joint.planar_vectors
+    [P_frame.y, P_frame.z]
+    >>> joint.rotation_coordinate
+    q0_PC(t)
+    >>> joint.planar_coordinates
+    Matrix([
+    [q1_PC(t)],
+    [q2_PC(t)]])
+    >>> joint.coordinates
+    Matrix([
+    [q0_PC(t)],
+    [q1_PC(t)],
+    [q2_PC(t)]])
+    >>> joint.rotation_speed
+    u0_PC(t)
+    >>> joint.planar_speeds
+    Matrix([
+    [u1_PC(t)],
+    [u2_PC(t)]])
+    >>> joint.speeds
+    Matrix([
+    [u0_PC(t)],
+    [u1_PC(t)],
+    [u2_PC(t)]])
+    >>> child.frame.ang_vel_in(parent.frame)
+    u0_PC(t)*P_frame.x
+    >>> child.frame.dcm(parent.frame)
+    Matrix([
+    [1,              0,             0],
+    [0,  cos(q0_PC(t)), sin(q0_PC(t))],
+    [0, -sin(q0_PC(t)), cos(q0_PC(t))]])
+    >>> joint.child_point.pos_from(joint.parent_point)
+    q1_PC(t)*P_frame.y + q2_PC(t)*P_frame.z
+    >>> child.masscenter.vel(parent.frame)
+    u1_PC(t)*P_frame.y + u2_PC(t)*P_frame.z
+
+    To further demonstrate the use of the planar joint, the kinematics of a
+    block sliding on a slope, can be created as follows.
+
+    >>> from sympy import symbols
+    >>> from sympy.physics.mechanics import PlanarJoint, RigidBody, ReferenceFrame
+    >>> a, d, h = symbols('a d h')
+
+    First create bodies to represent the slope and the block.
+
+    >>> ground = RigidBody('G')
+    >>> block = RigidBody('B')
+
+    To define the slope you can either define the plane by specifying the
+    ``planar_vectors`` or/and the ``rotation_axis``. However it is advisable to
+    create a rotated intermediate frame, so that the ``parent_vectors`` and
+    ``rotation_axis`` will be the unit vectors of this intermediate frame.
+
+    >>> slope = ReferenceFrame('A')
+    >>> slope.orient_axis(ground.frame, ground.y, a)
+
+    The planar joint can be created using these bodies and intermediate frame.
+    We can specify the origin of the slope to be ``d`` above the slope's center
+    of mass and the block's center of mass to be a distance ``h`` above the
+    slope's surface. Note that we can specify the normal of the plane using the
+    rotation axis argument.
+
+    >>> joint = PlanarJoint('PC', ground, block, parent_point=d * ground.x,
+    ...                     child_point=-h * block.x, parent_interframe=slope)
+
+    Once the joint is established the kinematics of the bodies can be accessed.
+    First the ``rotation_axis``, which is normal to the plane and the
+    ``plane_vectors``, can be found.
+
+    >>> joint.rotation_axis
+    A.x
+    >>> joint.planar_vectors
+    [A.y, A.z]
+
+    The direction cosine matrix of the block with respect to the ground can be
+    found with:
+
+    >>> block.frame.dcm(ground.frame)
+    Matrix([
+    [              cos(a),              0,              -sin(a)],
+    [sin(a)*sin(q0_PC(t)),  cos(q0_PC(t)), sin(q0_PC(t))*cos(a)],
+    [sin(a)*cos(q0_PC(t)), -sin(q0_PC(t)), cos(a)*cos(q0_PC(t))]])
+
+    The angular velocity of the block can be computed with respect to the
+    ground.
+
+    >>> block.frame.ang_vel_in(ground.frame)
+    u0_PC(t)*A.x
+
+    The position of the block's center of mass can be found with:
+
+    >>> block.masscenter.pos_from(ground.masscenter)
+    d*G_frame.x + h*B_frame.x + q1_PC(t)*A.y + q2_PC(t)*A.z
+
+    Finally, the linear velocity of the block's center of mass can be
+    computed with respect to the ground.
+
+    >>> block.masscenter.vel(ground.frame)
+    u1_PC(t)*A.y + u2_PC(t)*A.z
+
+    In some cases it could be your preference to only define the normals of the
+    plane with respect to both bodies. This can most easily be done by supplying
+    vectors to the ``interframe`` arguments. What will happen in this case is
+    that an interframe will be created with its ``x`` axis aligned with the
+    provided vector. For a further explanation of how this is done see the notes
+    of the ``Joint`` class. In the code below, the above example (with the block
+    on the slope) is recreated by supplying vectors to the interframe arguments.
+    Note that the previously described option is however more computationally
+    efficient, because the algorithm now has to compute the rotation angle
+    between the provided vector and the 'x' axis.
+
+    >>> from sympy import symbols, cos, sin
+    >>> from sympy.physics.mechanics import PlanarJoint, RigidBody
+    >>> a, d, h = symbols('a d h')
+    >>> ground = RigidBody('G')
+    >>> block = RigidBody('B')
+    >>> joint = PlanarJoint(
+    ...     'PC', ground, block, parent_point=d * ground.x,
+    ...     child_point=-h * block.x, child_interframe=block.x,
+    ...     parent_interframe=cos(a) * ground.x + sin(a) * ground.z)
+    >>> block.frame.dcm(ground.frame).simplify()
+    Matrix([
+    [               cos(a),              0,               sin(a)],
+    [-sin(a)*sin(q0_PC(t)),  cos(q0_PC(t)), sin(q0_PC(t))*cos(a)],
+    [-sin(a)*cos(q0_PC(t)), -sin(q0_PC(t)), cos(a)*cos(q0_PC(t))]])
+
+    """
+
+    def __init__(self, name, parent, child, rotation_coordinate=None,
+                 planar_coordinates=None, rotation_speed=None,
+                 planar_speeds=None, parent_point=None, child_point=None,
+                 parent_interframe=None, child_interframe=None):
+        # A ready to merge implementation of setting the planar_vectors and
+        # rotation_axis was added and removed in PR #24046
+        coordinates = (rotation_coordinate, planar_coordinates)
+        speeds = (rotation_speed, planar_speeds)
+        super().__init__(name, parent, child, coordinates, speeds,
+                         parent_point, child_point,
+                         parent_interframe=parent_interframe,
+                         child_interframe=child_interframe)
+
+    def __str__(self):
+        return (f'PlanarJoint: {self.name}  parent: {self.parent}  '
+                f'child: {self.child}')
+
+    @property
+    def rotation_coordinate(self):
+        """Generalized coordinate corresponding to the rotation angle."""
+        return self.coordinates[0]
+
+    @property
+    def planar_coordinates(self):
+        """Two generalized coordinates used for the planar translation."""
+        return self.coordinates[1:, 0]
+
+    @property
+    def rotation_speed(self):
+        """Generalized speed corresponding to the angular velocity."""
+        return self.speeds[0]
+
+    @property
+    def planar_speeds(self):
+        """Two generalized speeds used for the planar translation velocity."""
+        return self.speeds[1:, 0]
+
+    @property
+    def rotation_axis(self):
+        """The axis about which the rotation occurs."""
+        return self.parent_interframe.x
+
+    @property
+    def planar_vectors(self):
+        """The vectors that describe the planar translation directions."""
+        return [self.parent_interframe.y, self.parent_interframe.z]
+
+    def _generate_coordinates(self, coordinates):
+        rotation_speed = self._fill_coordinate_list(coordinates[0], 1, 'q',
+                                                    number_single=True)
+        planar_speeds = self._fill_coordinate_list(coordinates[1], 2, 'q', 1)
+        return rotation_speed.col_join(planar_speeds)
+
+    def _generate_speeds(self, speeds):
+        rotation_speed = self._fill_coordinate_list(speeds[0], 1, 'u',
+                                                    number_single=True)
+        planar_speeds = self._fill_coordinate_list(speeds[1], 2, 'u', 1)
+        return rotation_speed.col_join(planar_speeds)
+
+    def _orient_frames(self):
+        self.child_interframe.orient_axis(
+            self.parent_interframe, self.rotation_axis,
+            self.rotation_coordinate)
+
+    def _set_angular_velocity(self):
+        self.child_interframe.set_ang_vel(
+            self.parent_interframe,
+            self.rotation_speed * self.rotation_axis)
+
+    def _set_linear_velocity(self):
+        self.child_point.set_pos(
+            self.parent_point,
+            self.planar_coordinates[0] * self.planar_vectors[0] +
+            self.planar_coordinates[1] * self.planar_vectors[1])
+        self.parent_point.set_vel(self.parent_interframe, 0)
+        self.child_point.set_vel(self.child_interframe, 0)
+        self.child_point.set_vel(
+            self._parent_frame, self.planar_speeds[0] * self.planar_vectors[0] +
+            self.planar_speeds[1] * self.planar_vectors[1])
+        self.child.masscenter.v2pt_theory(self.child_point, self._parent_frame,
+                                          self._child_frame)
+
+
+class SphericalJoint(Joint):
+    """Spherical (Ball-and-Socket) Joint.
+
+    .. image:: SphericalJoint.svg
+        :align: center
+        :width: 600
+
+    Explanation
+    ===========
+
+    A spherical joint is defined such that the child body is free to rotate in
+    any direction, without allowing a translation of the ``child_point``. As can
+    also be seen in the image, the ``parent_point`` and ``child_point`` are
+    fixed on top of each other, i.e. the ``joint_point``. This rotation is
+    defined using the :func:`parent_interframe.orient(child_interframe,
+    rot_type, amounts, rot_order)
+    <sympy.physics.vector.frame.ReferenceFrame.orient>` method. The default
+    rotation consists of three relative rotations, i.e. body-fixed rotations.
+    Based on the direction cosine matrix following from these rotations, the
+    angular velocity is computed based on the generalized coordinates and
+    generalized speeds.
+
+    Parameters
+    ==========
+
+    name : string
+        A unique name for the joint.
+    parent : Particle or RigidBody or Body
+        The parent body of joint.
+    child : Particle or RigidBody or Body
+        The child body of joint.
+    coordinates: iterable of dynamicsymbols, optional
+        Generalized coordinates of the joint.
+    speeds : iterable of dynamicsymbols, optional
+        Generalized speeds of joint.
+    parent_point : Point or Vector, optional
+        Attachment point where the joint is fixed to the parent body. If a
+        vector is provided, then the attachment point is computed by adding the
+        vector to the body's mass center. The default value is the parent's mass
+        center.
+    child_point : Point or Vector, optional
+        Attachment point where the joint is fixed to the child body. If a
+        vector is provided, then the attachment point is computed by adding the
+        vector to the body's mass center. The default value is the child's mass
+        center.
+    parent_interframe : ReferenceFrame, optional
+        Intermediate frame of the parent body with respect to which the joint
+        transformation is formulated. If a Vector is provided then an interframe
+        is created which aligns its X axis with the given vector. The default
+        value is the parent's own frame.
+    child_interframe : ReferenceFrame, optional
+        Intermediate frame of the child body with respect to which the joint
+        transformation is formulated. If a Vector is provided then an interframe
+        is created which aligns its X axis with the given vector. The default
+        value is the child's own frame.
+    rot_type : str, optional
+        The method used to generate the direction cosine matrix. Supported
+        methods are:
+
+        - ``'Body'``: three successive rotations about new intermediate axes,
+          also called "Euler and Tait-Bryan angles"
+        - ``'Space'``: three successive rotations about the parent frames' unit
+          vectors
+
+        The default method is ``'Body'``.
+    amounts :
+        Expressions defining the rotation angles or direction cosine matrix.
+        These must match the ``rot_type``. See examples below for details. The
+        input types are:
+
+        - ``'Body'``: 3-tuple of expressions, symbols, or functions
+        - ``'Space'``: 3-tuple of expressions, symbols, or functions
+
+        The default amounts are the given ``coordinates``.
+    rot_order : str or int, optional
+        If applicable, the order of the successive of rotations. The string
+        ``'123'`` and integer ``123`` are equivalent, for example. Required for
+        ``'Body'`` and ``'Space'``. The default value is ``123``.
+
+    Attributes
+    ==========
+
+    name : string
+        The joint's name.
+    parent : Particle or RigidBody or Body
+        The joint's parent body.
+    child : Particle or RigidBody or Body
+        The joint's child body.
+    coordinates : Matrix
+        Matrix of the joint's generalized coordinates.
+    speeds : Matrix
+        Matrix of the joint's generalized speeds.
+    parent_point : Point
+        Attachment point where the joint is fixed to the parent body.
+    child_point : Point
+        Attachment point where the joint is fixed to the child body.
+    parent_interframe : ReferenceFrame
+        Intermediate frame of the parent body with respect to which the joint
+        transformation is formulated.
+    child_interframe : ReferenceFrame
+        Intermediate frame of the child body with respect to which the joint
+        transformation is formulated.
+    kdes : Matrix
+        Kinematical differential equations of the joint.
+
+    Examples
+    =========
+
+    A single spherical joint is created from two bodies and has the following
+    basic attributes:
+
+    >>> from sympy.physics.mechanics import RigidBody, SphericalJoint
+    >>> parent = RigidBody('P')
+    >>> parent
+    P
+    >>> child = RigidBody('C')
+    >>> child
+    C
+    >>> joint = SphericalJoint('PC', parent, child)
+    >>> joint
+    SphericalJoint: PC  parent: P  child: C
+    >>> joint.name
+    'PC'
+    >>> joint.parent
+    P
+    >>> joint.child
+    C
+    >>> joint.parent_point
+    P_masscenter
+    >>> joint.child_point
+    C_masscenter
+    >>> joint.parent_interframe
+    P_frame
+    >>> joint.child_interframe
+    C_frame
+    >>> joint.coordinates
+    Matrix([
+    [q0_PC(t)],
+    [q1_PC(t)],
+    [q2_PC(t)]])
+    >>> joint.speeds
+    Matrix([
+    [u0_PC(t)],
+    [u1_PC(t)],
+    [u2_PC(t)]])
+    >>> child.frame.ang_vel_in(parent.frame).to_matrix(child.frame)
+    Matrix([
+    [ u0_PC(t)*cos(q1_PC(t))*cos(q2_PC(t)) + u1_PC(t)*sin(q2_PC(t))],
+    [-u0_PC(t)*sin(q2_PC(t))*cos(q1_PC(t)) + u1_PC(t)*cos(q2_PC(t))],
+    [                             u0_PC(t)*sin(q1_PC(t)) + u2_PC(t)]])
+    >>> child.frame.x.to_matrix(parent.frame)
+    Matrix([
+    [                                            cos(q1_PC(t))*cos(q2_PC(t))],
+    [sin(q0_PC(t))*sin(q1_PC(t))*cos(q2_PC(t)) + sin(q2_PC(t))*cos(q0_PC(t))],
+    [sin(q0_PC(t))*sin(q2_PC(t)) - sin(q1_PC(t))*cos(q0_PC(t))*cos(q2_PC(t))]])
+    >>> joint.child_point.pos_from(joint.parent_point)
+    0
+
+    To further demonstrate the use of the spherical joint, the kinematics of a
+    spherical joint with a ZXZ rotation can be created as follows.
+
+    >>> from sympy import symbols
+    >>> from sympy.physics.mechanics import RigidBody, SphericalJoint
+    >>> l1 = symbols('l1')
+
+    First create bodies to represent the fixed floor and a pendulum bob.
+
+    >>> floor = RigidBody('F')
+    >>> bob = RigidBody('B')
+
+    The joint will connect the bob to the floor, with the joint located at a
+    distance of ``l1`` from the child's center of mass and the rotation set to a
+    body-fixed ZXZ rotation.
+
+    >>> joint = SphericalJoint('S', floor, bob, child_point=l1 * bob.y,
+    ...                        rot_type='body', rot_order='ZXZ')
+
+    Now that the joint is established, the kinematics of the connected body can
+    be accessed.
+
+    The position of the bob's masscenter is found with:
+
+    >>> bob.masscenter.pos_from(floor.masscenter)
+    - l1*B_frame.y
+
+    The angular velocities of the pendulum link can be computed with respect to
+    the floor.
+
+    >>> bob.frame.ang_vel_in(floor.frame).to_matrix(
+    ...     floor.frame).simplify()
+    Matrix([
+    [u1_S(t)*cos(q0_S(t)) + u2_S(t)*sin(q0_S(t))*sin(q1_S(t))],
+    [u1_S(t)*sin(q0_S(t)) - u2_S(t)*sin(q1_S(t))*cos(q0_S(t))],
+    [                          u0_S(t) + u2_S(t)*cos(q1_S(t))]])
+
+    Finally, the linear velocity of the bob's center of mass can be computed.
+
+    >>> bob.masscenter.vel(floor.frame).to_matrix(bob.frame)
+    Matrix([
+    [                           l1*(u0_S(t)*cos(q1_S(t)) + u2_S(t))],
+    [                                                             0],
+    [-l1*(u0_S(t)*sin(q1_S(t))*sin(q2_S(t)) + u1_S(t)*cos(q2_S(t)))]])
+
+    """
+    def __init__(self, name, parent, child, coordinates=None, speeds=None,
+                 parent_point=None, child_point=None, parent_interframe=None,
+                 child_interframe=None, rot_type='BODY', amounts=None,
+                 rot_order=123):
+        self._rot_type = rot_type
+        self._amounts = amounts
+        self._rot_order = rot_order
+        super().__init__(name, parent, child, coordinates, speeds,
+                         parent_point, child_point,
+                         parent_interframe=parent_interframe,
+                         child_interframe=child_interframe)
+
+    def __str__(self):
+        return (f'SphericalJoint: {self.name}  parent: {self.parent}  '
+                f'child: {self.child}')
+
+    def _generate_coordinates(self, coordinates):
+        return self._fill_coordinate_list(coordinates, 3, 'q')
+
+    def _generate_speeds(self, speeds):
+        return self._fill_coordinate_list(speeds, len(self.coordinates), 'u')
+
+    def _orient_frames(self):
+        supported_rot_types = ('BODY', 'SPACE')
+        if self._rot_type.upper() not in supported_rot_types:
+            raise NotImplementedError(
+                f'Rotation type "{self._rot_type}" is not implemented. '
+                f'Implemented rotation types are: {supported_rot_types}')
+        amounts = self.coordinates if self._amounts is None else self._amounts
+        self.child_interframe.orient(self.parent_interframe, self._rot_type,
+                                     amounts, self._rot_order)
+
+    def _set_angular_velocity(self):
+        t = dynamicsymbols._t
+        vel = self.child_interframe.ang_vel_in(self.parent_interframe).xreplace(
+            {q.diff(t): u for q, u in zip(self.coordinates, self.speeds)}
+        )
+        self.child_interframe.set_ang_vel(self.parent_interframe, vel)
+
+    def _set_linear_velocity(self):
+        self.child_point.set_pos(self.parent_point, 0)
+        self.parent_point.set_vel(self._parent_frame, 0)
+        self.child_point.set_vel(self._child_frame, 0)
+        self.child.masscenter.v2pt_theory(self.parent_point, self._parent_frame,
+                                          self._child_frame)
+
+
+class WeldJoint(Joint):
+    """Weld Joint.
+
+    .. raw:: html
+        :file: ../../../doc/src/modules/physics/mechanics/api/WeldJoint.svg
+
+    Explanation
+    ===========
+
+    A weld joint is defined such that there is no relative motion between the
+    child and parent bodies. The direction cosine matrix between the attachment
+    frame (``parent_interframe`` and ``child_interframe``) is the identity
+    matrix and the attachment points (``parent_point`` and ``child_point``) are
+    coincident. The page on the joints framework gives a more detailed
+    explanation of the intermediate frames.
+
+    Parameters
+    ==========
+
+    name : string
+        A unique name for the joint.
+    parent : Particle or RigidBody or Body
+        The parent body of joint.
+    child : Particle or RigidBody or Body
+        The child body of joint.
+    parent_point : Point or Vector, optional
+        Attachment point where the joint is fixed to the parent body. If a
+        vector is provided, then the attachment point is computed by adding the
+        vector to the body's mass center. The default value is the parent's mass
+        center.
+    child_point : Point or Vector, optional
+        Attachment point where the joint is fixed to the child body. If a
+        vector is provided, then the attachment point is computed by adding the
+        vector to the body's mass center. The default value is the child's mass
+        center.
+    parent_interframe : ReferenceFrame, optional
+        Intermediate frame of the parent body with respect to which the joint
+        transformation is formulated. If a Vector is provided then an interframe
+        is created which aligns its X axis with the given vector. The default
+        value is the parent's own frame.
+    child_interframe : ReferenceFrame, optional
+        Intermediate frame of the child body with respect to which the joint
+        transformation is formulated. If a Vector is provided then an interframe
+        is created which aligns its X axis with the given vector. The default
+        value is the child's own frame.
+
+    Attributes
+    ==========
+
+    name : string
+        The joint's name.
+    parent : Particle or RigidBody or Body
+        The joint's parent body.
+    child : Particle or RigidBody or Body
+        The joint's child body.
+    coordinates : Matrix
+        Matrix of the joint's generalized coordinates. The default value is
+        ``dynamicsymbols(f'q_{joint.name}')``.
+    speeds : Matrix
+        Matrix of the joint's generalized speeds. The default value is
+        ``dynamicsymbols(f'u_{joint.name}')``.
+    parent_point : Point
+        Attachment point where the joint is fixed to the parent body.
+    child_point : Point
+        Attachment point where the joint is fixed to the child body.
+    parent_interframe : ReferenceFrame
+        Intermediate frame of the parent body with respect to which the joint
+        transformation is formulated.
+    child_interframe : ReferenceFrame
+        Intermediate frame of the child body with respect to which the joint
+        transformation is formulated.
+    kdes : Matrix
+        Kinematical differential equations of the joint.
+
+    Examples
+    =========
+
+    A single weld joint is created from two bodies and has the following basic
+    attributes:
+
+    >>> from sympy.physics.mechanics import RigidBody, WeldJoint
+    >>> parent = RigidBody('P')
+    >>> parent
+    P
+    >>> child = RigidBody('C')
+    >>> child
+    C
+    >>> joint = WeldJoint('PC', parent, child)
+    >>> joint
+    WeldJoint: PC  parent: P  child: C
+    >>> joint.name
+    'PC'
+    >>> joint.parent
+    P
+    >>> joint.child
+    C
+    >>> joint.parent_point
+    P_masscenter
+    >>> joint.child_point
+    C_masscenter
+    >>> joint.coordinates
+    Matrix(0, 0, [])
+    >>> joint.speeds
+    Matrix(0, 0, [])
+    >>> child.frame.ang_vel_in(parent.frame)
+    0
+    >>> child.frame.dcm(parent.frame)
+    Matrix([
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1]])
+    >>> joint.child_point.pos_from(joint.parent_point)
+    0
+
+    To further demonstrate the use of the weld joint, two relatively-fixed
+    bodies rotated by a quarter turn about the Y axis can be created as follows:
+
+    >>> from sympy import symbols, pi
+    >>> from sympy.physics.mechanics import ReferenceFrame, RigidBody, WeldJoint
+    >>> l1, l2 = symbols('l1 l2')
+
+    First create the bodies to represent the parent and rotated child body.
+
+    >>> parent = RigidBody('P')
+    >>> child = RigidBody('C')
+
+    Next the intermediate frame specifying the fixed rotation with respect to
+    the parent can be created.
+
+    >>> rotated_frame = ReferenceFrame('Pr')
+    >>> rotated_frame.orient_axis(parent.frame, parent.y, pi / 2)
+
+    The weld between the parent body and child body is located at a distance
+    ``l1`` from the parent's center of mass in the X direction and ``l2`` from
+    the child's center of mass in the child's negative X direction.
+
+    >>> weld = WeldJoint('weld', parent, child, parent_point=l1 * parent.x,
+    ...                  child_point=-l2 * child.x,
+    ...                  parent_interframe=rotated_frame)
+
+    Now that the joint has been established, the kinematics of the bodies can be
+    accessed. The direction cosine matrix of the child body with respect to the
+    parent can be found:
+
+    >>> child.frame.dcm(parent.frame)
+    Matrix([
+    [0, 0, -1],
+    [0, 1,  0],
+    [1, 0,  0]])
+
+    As can also been seen from the direction cosine matrix, the parent X axis is
+    aligned with the child's Z axis:
+    >>> parent.x == child.z
+    True
+
+    The position of the child's center of mass with respect to the parent's
+    center of mass can be found with:
+
+    >>> child.masscenter.pos_from(parent.masscenter)
+    l1*P_frame.x + l2*C_frame.x
+
+    The angular velocity of the child with respect to the parent is 0 as one
+    would expect.
+
+    >>> child.frame.ang_vel_in(parent.frame)
+    0
+
+    """
+
+    def __init__(self, name, parent, child, parent_point=None, child_point=None,
+                 parent_interframe=None, child_interframe=None):
+        super().__init__(name, parent, child, [], [], parent_point,
+                         child_point, parent_interframe=parent_interframe,
+                         child_interframe=child_interframe)
+        self._kdes = Matrix(1, 0, []).T  # Removes stackability problems #10770
+
+    def __str__(self):
+        return (f'WeldJoint: {self.name}  parent: {self.parent}  '
+                f'child: {self.child}')
+
+    def _generate_coordinates(self, coordinate):
+        return Matrix()
+
+    def _generate_speeds(self, speed):
+        return Matrix()
+
+    def _orient_frames(self):
+        self.child_interframe.orient_axis(self.parent_interframe,
+                                          self.parent_interframe.x, 0)
+
+    def _set_angular_velocity(self):
+        self.child_interframe.set_ang_vel(self.parent_interframe, 0)
+
+    def _set_linear_velocity(self):
+        self.child_point.set_pos(self.parent_point, 0)
+        self.parent_point.set_vel(self._parent_frame, 0)
+        self.child_point.set_vel(self._child_frame, 0)
+        self.child.masscenter.set_vel(self._parent_frame, 0)

lib/python3.12/site-packages/sympy/physics/mechanics/jointsmethod.py

@@ -0,0 +1,318 @@
+from sympy.physics.mechanics import (Body, Lagrangian, KanesMethod, LagrangesMethod,
+                                    RigidBody, Particle)
+from sympy.physics.mechanics.body_base import BodyBase
+from sympy.physics.mechanics.method import _Methods
+from sympy import Matrix
+from sympy.utilities.exceptions import sympy_deprecation_warning
+
+__all__ = ['JointsMethod']
+
+
+class JointsMethod(_Methods):
+    """Method for formulating the equations of motion using a set of interconnected bodies with joints.
+
+    .. deprecated:: 1.13
+        The JointsMethod class is deprecated. Its functionality has been
+        replaced by the new :class:`~.System` class.
+
+    Parameters
+    ==========
+
+    newtonion : Body or ReferenceFrame
+        The newtonion(inertial) frame.
+    *joints : Joint
+        The joints in the system
+
+    Attributes
+    ==========
+
+    q, u : iterable
+        Iterable of the generalized coordinates and speeds
+    bodies : iterable
+        Iterable of Body objects in the system.
+    loads : iterable
+        Iterable of (Point, vector) or (ReferenceFrame, vector) tuples
+        describing the forces on the system.
+    mass_matrix : Matrix, shape(n, n)
+        The system's mass matrix
+    forcing : Matrix, shape(n, 1)
+        The system's forcing vector
+    mass_matrix_full : Matrix, shape(2*n, 2*n)
+        The "mass matrix" for the u's and q's
+    forcing_full : Matrix, shape(2*n, 1)
+        The "forcing vector" for the u's and q's
+    method : KanesMethod or Lagrange's method
+        Method's object.
+    kdes : iterable
+        Iterable of kde in they system.
+
+    Examples
+    ========
+
+    As Body and JointsMethod have been deprecated, the following examples are
+    for illustrative purposes only. The functionality of Body is fully captured
+    by :class:`~.RigidBody` and :class:`~.Particle` and the functionality of
+    JointsMethod is fully captured by :class:`~.System`. To ignore the
+    deprecation warning we can use the ignore_warnings context manager.
+
+    >>> from sympy.utilities.exceptions import ignore_warnings
+
+    This is a simple example for a one degree of freedom translational
+    spring-mass-damper.
+
+    >>> from sympy import symbols
+    >>> from sympy.physics.mechanics import Body, JointsMethod, PrismaticJoint
+    >>> from sympy.physics.vector import dynamicsymbols
+    >>> c, k = symbols('c k')
+    >>> x, v = dynamicsymbols('x v')
+    >>> with ignore_warnings(DeprecationWarning):
+    ...     wall = Body('W')
+    ...     body = Body('B')
+    >>> J = PrismaticJoint('J', wall, body, coordinates=x, speeds=v)
+    >>> wall.apply_force(c*v*wall.x, reaction_body=body)
+    >>> wall.apply_force(k*x*wall.x, reaction_body=body)
+    >>> with ignore_warnings(DeprecationWarning):
+    ...     method = JointsMethod(wall, J)
+    >>> method.form_eoms()
+    Matrix([[-B_mass*Derivative(v(t), t) - c*v(t) - k*x(t)]])
+    >>> M = method.mass_matrix_full
+    >>> F = method.forcing_full
+    >>> rhs = M.LUsolve(F)
+    >>> rhs
+    Matrix([
+    [                     v(t)],
+    [(-c*v(t) - k*x(t))/B_mass]])
+
+    Notes
+    =====
+
+    ``JointsMethod`` currently only works with systems that do not have any
+    configuration or motion constraints.
+
+    """
+
+    def __init__(self, newtonion, *joints):
+        sympy_deprecation_warning(
+            """
+            The JointsMethod class is deprecated.
+            Its functionality has been replaced by the new System class.
+            """,
+            deprecated_since_version="1.13",
+            active_deprecations_target="deprecated-mechanics-jointsmethod"
+        )
+        if isinstance(newtonion, BodyBase):
+            self.frame = newtonion.frame
+        else:
+            self.frame = newtonion
+
+        self._joints = joints
+        self._bodies = self._generate_bodylist()
+        self._loads = self._generate_loadlist()
+        self._q = self._generate_q()
+        self._u = self._generate_u()
+        self._kdes = self._generate_kdes()
+
+        self._method = None
+
+    @property
+    def bodies(self):
+        """List of bodies in they system."""
+        return self._bodies
+
+    @property
+    def loads(self):
+        """List of loads on the system."""
+        return self._loads
+
+    @property
+    def q(self):
+        """List of the generalized coordinates."""
+        return self._q
+
+    @property
+    def u(self):
+        """List of the generalized speeds."""
+        return self._u
+
+    @property
+    def kdes(self):
+        """List of the generalized coordinates."""
+        return self._kdes
+
+    @property
+    def forcing_full(self):
+        """The "forcing vector" for the u's and q's."""
+        return self.method.forcing_full
+
+    @property
+    def mass_matrix_full(self):
+        """The "mass matrix" for the u's and q's."""
+        return self.method.mass_matrix_full
+
+    @property
+    def mass_matrix(self):
+        """The system's mass matrix."""
+        return self.method.mass_matrix
+
+    @property
+    def forcing(self):
+        """The system's forcing vector."""
+        return self.method.forcing
+
+    @property
+    def method(self):
+        """Object of method used to form equations of systems."""
+        return self._method
+
+    def _generate_bodylist(self):
+        bodies = []
+        for joint in self._joints:
+            if joint.child not in bodies:
+                bodies.append(joint.child)
+            if joint.parent not in bodies:
+                bodies.append(joint.parent)
+        return bodies
+
+    def _generate_loadlist(self):
+        load_list = []
+        for body in self.bodies:
+            if isinstance(body, Body):
+                load_list.extend(body.loads)
+        return load_list
+
+    def _generate_q(self):
+        q_ind = []
+        for joint in self._joints:
+            for coordinate in joint.coordinates:
+                if coordinate in q_ind:
+                    raise ValueError('Coordinates of joints should be unique.')
+                q_ind.append(coordinate)
+        return Matrix(q_ind)
+
+    def _generate_u(self):
+        u_ind = []
+        for joint in self._joints:
+            for speed in joint.speeds:
+                if speed in u_ind:
+                    raise ValueError('Speeds of joints should be unique.')
+                u_ind.append(speed)
+        return Matrix(u_ind)
+
+    def _generate_kdes(self):
+        kd_ind = Matrix(1, 0, []).T
+        for joint in self._joints:
+            kd_ind = kd_ind.col_join(joint.kdes)
+        return kd_ind
+
+    def _convert_bodies(self):
+        # Convert `Body` to `Particle` and `RigidBody`
+        bodylist = []
+        for body in self.bodies:
+            if not isinstance(body, Body):
+                bodylist.append(body)
+                continue
+            if body.is_rigidbody:
+                rb = RigidBody(body.name, body.masscenter, body.frame, body.mass,
+                    (body.central_inertia, body.masscenter))
+                rb.potential_energy = body.potential_energy
+                bodylist.append(rb)
+            else:
+                part = Particle(body.name, body.masscenter, body.mass)
+                part.potential_energy = body.potential_energy
+                bodylist.append(part)
+        return bodylist
+
+    def form_eoms(self, method=KanesMethod):
+        """Method to form system's equation of motions.
+
+        Parameters
+        ==========
+
+        method : Class
+            Class name of method.
+
+        Returns
+        ========
+
+        Matrix
+            Vector of equations of motions.
+
+        Examples
+        ========
+
+        As Body and JointsMethod have been deprecated, the following examples
+        are for illustrative purposes only. The functionality of Body is fully
+        captured by :class:`~.RigidBody` and :class:`~.Particle` and the
+        functionality of JointsMethod is fully captured by :class:`~.System`. To
+        ignore the deprecation warning we can use the ignore_warnings context
+        manager.
+
+        >>> from sympy.utilities.exceptions import ignore_warnings
+
+        This is a simple example for a one degree of freedom translational
+        spring-mass-damper.
+
+        >>> from sympy import S, symbols
+        >>> from sympy.physics.mechanics import LagrangesMethod, dynamicsymbols, Body
+        >>> from sympy.physics.mechanics import PrismaticJoint, JointsMethod
+        >>> q = dynamicsymbols('q')
+        >>> qd = dynamicsymbols('q', 1)
+        >>> m, k, b = symbols('m k b')
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     wall = Body('W')
+        ...     part = Body('P', mass=m)
+        >>> part.potential_energy = k * q**2 / S(2)
+        >>> J = PrismaticJoint('J', wall, part, coordinates=q, speeds=qd)
+        >>> wall.apply_force(b * qd * wall.x, reaction_body=part)
+        >>> with ignore_warnings(DeprecationWarning):
+        ...     method = JointsMethod(wall, J)
+        >>> method.form_eoms(LagrangesMethod)
+        Matrix([[b*Derivative(q(t), t) + k*q(t) + m*Derivative(q(t), (t, 2))]])
+
+        We can also solve for the states using the 'rhs' method.
+
+        >>> method.rhs()
+        Matrix([
+        [                Derivative(q(t), t)],
+        [(-b*Derivative(q(t), t) - k*q(t))/m]])
+
+        """
+
+        bodylist = self._convert_bodies()
+        if issubclass(method, LagrangesMethod): #LagrangesMethod or similar
+            L = Lagrangian(self.frame, *bodylist)
+            self._method = method(L, self.q, self.loads, bodylist, self.frame)
+        else: #KanesMethod or similar
+            self._method = method(self.frame, q_ind=self.q, u_ind=self.u, kd_eqs=self.kdes,
+                                    forcelist=self.loads, bodies=bodylist)
+        soln = self.method._form_eoms()
+        return soln
+
+    def rhs(self, inv_method=None):
+        """Returns equations that can be solved numerically.
+
+        Parameters
+        ==========
+
+        inv_method : str
+            The specific sympy inverse matrix calculation method to use. For a
+            list of valid methods, see
+            :meth:`~sympy.matrices.matrixbase.MatrixBase.inv`
+
+        Returns
+        ========
+
+        Matrix
+            Numerically solvable equations.
+
+        See Also
+        ========
+
+        sympy.physics.mechanics.kane.KanesMethod.rhs:
+            KanesMethod's rhs function.
+        sympy.physics.mechanics.lagrange.LagrangesMethod.rhs:
+            LagrangesMethod's rhs function.
+
+        """
+
+        return self.method.rhs(inv_method=inv_method)

lib/python3.12/site-packages/sympy/physics/mechanics/kane.py

@@ -0,0 +1,860 @@
+from sympy import zeros, Matrix, diff, eye
+from sympy.core.sorting import default_sort_key
+from sympy.physics.vector import (ReferenceFrame, dynamicsymbols,
+                                  partial_velocity)
+from sympy.physics.mechanics.method import _Methods
+from sympy.physics.mechanics.particle import Particle
+from sympy.physics.mechanics.rigidbody import RigidBody
+from sympy.physics.mechanics.functions import (msubs, find_dynamicsymbols,
+                                               _f_list_parser,
+                                               _validate_coordinates,
+                                               _parse_linear_solver)
+from sympy.physics.mechanics.linearize import Linearizer
+from sympy.utilities.iterables import iterable
+
+__all__ = ['KanesMethod']
+
+
+class KanesMethod(_Methods):
+    r"""Kane's method object.
+
+    Explanation
+    ===========
+
+    This object is used to do the "book-keeping" as you go through and form
+    equations of motion in the way Kane presents in:
+    Kane, T., Levinson, D. Dynamics Theory and Applications. 1985 McGraw-Hill
+
+    The attributes are for equations in the form [M] udot = forcing.
+
+    Attributes
+    ==========
+
+    q, u : Matrix
+        Matrices of the generalized coordinates and speeds
+    bodies : iterable
+        Iterable of Particle and RigidBody objects in the system.
+    loads : iterable
+        Iterable of (Point, vector) or (ReferenceFrame, vector) tuples
+        describing the forces on the system.
+    auxiliary_eqs : Matrix
+        If applicable, the set of auxiliary Kane's
+        equations used to solve for non-contributing
+        forces.
+    mass_matrix : Matrix
+        The system's dynamics mass matrix: [k_d; k_dnh]
+    forcing : Matrix
+        The system's dynamics forcing vector: -[f_d; f_dnh]
+    mass_matrix_kin : Matrix
+        The "mass matrix" for kinematic differential equations: k_kqdot
+    forcing_kin : Matrix
+        The forcing vector for kinematic differential equations: -(k_ku*u + f_k)
+    mass_matrix_full : Matrix
+        The "mass matrix" for the u's and q's with dynamics and kinematics
+    forcing_full : Matrix
+        The "forcing vector" for the u's and q's with dynamics and kinematics
+
+    Parameters
+    ==========
+
+    frame : ReferenceFrame
+        The inertial reference frame for the system.
+    q_ind : iterable of dynamicsymbols
+        Independent generalized coordinates.
+    u_ind : iterable of dynamicsymbols
+        Independent generalized speeds.
+    kd_eqs : iterable of Expr, optional
+        Kinematic differential equations, which linearly relate the generalized
+        speeds to the time-derivatives of the generalized coordinates.
+    q_dependent : iterable of dynamicsymbols, optional
+        Dependent generalized coordinates.
+    configuration_constraints : iterable of Expr, optional
+        Constraints on the system's configuration, i.e. holonomic constraints.
+    u_dependent : iterable of dynamicsymbols, optional
+        Dependent generalized speeds.
+    velocity_constraints : iterable of Expr, optional
+        Constraints on the system's velocity, i.e. the combination of the
+        nonholonomic constraints and the time-derivative of the holonomic
+        constraints.
+    acceleration_constraints : iterable of Expr, optional
+        Constraints on the system's acceleration, by default these are the
+        time-derivative of the velocity constraints.
+    u_auxiliary : iterable of dynamicsymbols, optional
+        Auxiliary generalized speeds.
+    bodies : iterable of Particle and/or RigidBody, optional
+        The particles and rigid bodies in the system.
+    forcelist : iterable of tuple[Point | ReferenceFrame, Vector], optional
+        Forces and torques applied on the system.
+    explicit_kinematics : bool
+        Boolean whether the mass matrices and forcing vectors should use the
+        explicit form (default) or implicit form for kinematics.
+        See the notes for more details.
+    kd_eqs_solver : str, callable
+        Method used to solve the kinematic differential equations. If a string
+        is supplied, it should be a valid method that can be used with the
+        :meth:`sympy.matrices.matrixbase.MatrixBase.solve`. If a callable is
+        supplied, it should have the format ``f(A, rhs)``, where it solves the
+        equations and returns the solution. The default utilizes LU solve. See
+        the notes for more information.
+    constraint_solver : str, callable
+        Method used to solve the velocity constraints. If a string is
+        supplied, it should be a valid method that can be used with the
+        :meth:`sympy.matrices.matrixbase.MatrixBase.solve`. If a callable is
+        supplied, it should have the format ``f(A, rhs)``, where it solves the
+        equations and returns the solution. The default utilizes LU solve. See
+        the notes for more information.
+
+    Notes
+    =====
+
+    The mass matrices and forcing vectors related to kinematic equations
+    are given in the explicit form by default. In other words, the kinematic
+    mass matrix is $\mathbf{k_{k\dot{q}}} = \mathbf{I}$.
+    In order to get the implicit form of those matrices/vectors, you can set the
+    ``explicit_kinematics`` attribute to ``False``. So $\mathbf{k_{k\dot{q}}}$
+    is not necessarily an identity matrix. This can provide more compact
+    equations for non-simple kinematics.
+
+    Two linear solvers can be supplied to ``KanesMethod``: one for solving the
+    kinematic differential equations and one to solve the velocity constraints.
+    Both of these sets of equations can be expressed as a linear system ``Ax = rhs``,
+    which have to be solved in order to obtain the equations of motion.
+
+    The default solver ``'LU'``, which stands for LU solve, results relatively low
+    number of operations. The weakness of this method is that it can result in zero
+    division errors.
+
+    If zero divisions are encountered, a possible solver which may solve the problem
+    is ``"CRAMER"``. This method uses Cramer's rule to solve the system. This method
+    is slower and results in more operations than the default solver. However it only
+    uses a single division by default per entry of the solution.
+
+    While a valid list of solvers can be found at
+    :meth:`sympy.matrices.matrixbase.MatrixBase.solve`, it is also possible to supply a
+    `callable`. This way it is possible to use a different solver routine. If the
+    kinematic differential equations are not too complex it can be worth it to simplify
+    the solution by using ``lambda A, b: simplify(Matrix.LUsolve(A, b))``. Another
+    option solver one may use is :func:`sympy.solvers.solveset.linsolve`. This can be
+    done using `lambda A, b: tuple(linsolve((A, b)))[0]`, where we select the first
+    solution as our system should have only one unique solution.
+
+    Examples
+    ========
+
+    This is a simple example for a one degree of freedom translational
+    spring-mass-damper.
+
+    In this example, we first need to do the kinematics.
+    This involves creating generalized speeds and coordinates and their
+    derivatives.
+    Then we create a point and set its velocity in a frame.
+
+        >>> from sympy import symbols
+        >>> from sympy.physics.mechanics import dynamicsymbols, ReferenceFrame
+        >>> from sympy.physics.mechanics import Point, Particle, KanesMethod
+        >>> q, u = dynamicsymbols('q u')
+        >>> qd, ud = dynamicsymbols('q u', 1)
+        >>> m, c, k = symbols('m c k')
+        >>> N = ReferenceFrame('N')
+        >>> P = Point('P')
+        >>> P.set_vel(N, u * N.x)
+
+    Next we need to arrange/store information in the way that KanesMethod
+    requires. The kinematic differential equations should be an iterable of
+    expressions. A list of forces/torques must be constructed, where each entry
+    in the list is a (Point, Vector) or (ReferenceFrame, Vector) tuple, where
+    the Vectors represent the Force or Torque.
+    Next a particle needs to be created, and it needs to have a point and mass
+    assigned to it.
+    Finally, a list of all bodies and particles needs to be created.
+
+        >>> kd = [qd - u]
+        >>> FL = [(P, (-k * q - c * u) * N.x)]
+        >>> pa = Particle('pa', P, m)
+        >>> BL = [pa]
+
+    Finally we can generate the equations of motion.
+    First we create the KanesMethod object and supply an inertial frame,
+    coordinates, generalized speeds, and the kinematic differential equations.
+    Additional quantities such as configuration and motion constraints,
+    dependent coordinates and speeds, and auxiliary speeds are also supplied
+    here (see the online documentation).
+    Next we form FR* and FR to complete: Fr + Fr* = 0.
+    We have the equations of motion at this point.
+    It makes sense to rearrange them though, so we calculate the mass matrix and
+    the forcing terms, for E.o.M. in the form: [MM] udot = forcing, where MM is
+    the mass matrix, udot is a vector of the time derivatives of the
+    generalized speeds, and forcing is a vector representing "forcing" terms.
+
+        >>> KM = KanesMethod(N, q_ind=[q], u_ind=[u], kd_eqs=kd)
+        >>> (fr, frstar) = KM.kanes_equations(BL, FL)
+        >>> MM = KM.mass_matrix
+        >>> forcing = KM.forcing
+        >>> rhs = MM.inv() * forcing
+        >>> rhs
+        Matrix([[(-c*u(t) - k*q(t))/m]])
+        >>> KM.linearize(A_and_B=True)[0]
+        Matrix([
+        [   0,    1],
+        [-k/m, -c/m]])
+
+    Please look at the documentation pages for more information on how to
+    perform linearization and how to deal with dependent coordinates & speeds,
+    and how do deal with bringing non-contributing forces into evidence.
+
+    """
+
+    def __init__(self, frame, q_ind, u_ind, kd_eqs=None, q_dependent=None,
+                 configuration_constraints=None, u_dependent=None,
+                 velocity_constraints=None, acceleration_constraints=None,
+                 u_auxiliary=None, bodies=None, forcelist=None,
+                 explicit_kinematics=True, kd_eqs_solver='LU',
+                 constraint_solver='LU'):
+
+        """Please read the online documentation. """
+        if not q_ind:
+            q_ind = [dynamicsymbols('dummy_q')]
+            kd_eqs = [dynamicsymbols('dummy_kd')]
+
+        if not isinstance(frame, ReferenceFrame):
+            raise TypeError('An inertial ReferenceFrame must be supplied')
+        self._inertial = frame
+
+        self._fr = None
+        self._frstar = None
+
+        self._forcelist = forcelist
+        self._bodylist = bodies
+
+        self.explicit_kinematics = explicit_kinematics
+        self._constraint_solver = constraint_solver
+        self._initialize_vectors(q_ind, q_dependent, u_ind, u_dependent,
+                u_auxiliary)
+        _validate_coordinates(self.q, self.u)
+        self._initialize_kindiffeq_matrices(kd_eqs, kd_eqs_solver)
+        self._initialize_constraint_matrices(
+            configuration_constraints, velocity_constraints,
+            acceleration_constraints, constraint_solver)
+
+    def _initialize_vectors(self, q_ind, q_dep, u_ind, u_dep, u_aux):
+        """Initialize the coordinate and speed vectors."""
+
+        none_handler = lambda x: Matrix(x) if x else Matrix()
+
+        # Initialize generalized coordinates
+        q_dep = none_handler(q_dep)
+        if not iterable(q_ind):
+            raise TypeError('Generalized coordinates must be an iterable.')
+        if not iterable(q_dep):
+            raise TypeError('Dependent coordinates must be an iterable.')
+        q_ind = Matrix(q_ind)
+        self._qdep = q_dep
+        self._q = Matrix([q_ind, q_dep])
+        self._qdot = self.q.diff(dynamicsymbols._t)
+
+        # Initialize generalized speeds
+        u_dep = none_handler(u_dep)
+        if not iterable(u_ind):
+            raise TypeError('Generalized speeds must be an iterable.')
+        if not iterable(u_dep):
+            raise TypeError('Dependent speeds must be an iterable.')
+        u_ind = Matrix(u_ind)
+        self._udep = u_dep
+        self._u = Matrix([u_ind, u_dep])
+        self._udot = self.u.diff(dynamicsymbols._t)
+        self._uaux = none_handler(u_aux)
+
+    def _initialize_constraint_matrices(self, config, vel, acc, linear_solver='LU'):
+        """Initializes constraint matrices."""
+        linear_solver = _parse_linear_solver(linear_solver)
+        # Define vector dimensions
+        o = len(self.u)
+        m = len(self._udep)
+        p = o - m
+        none_handler = lambda x: Matrix(x) if x else Matrix()
+
+        # Initialize configuration constraints
+        config = none_handler(config)
+        if len(self._qdep) != len(config):
+            raise ValueError('There must be an equal number of dependent '
+                             'coordinates and configuration constraints.')
+        self._f_h = none_handler(config)
+
+        # Initialize velocity and acceleration constraints
+        vel = none_handler(vel)
+        acc = none_handler(acc)
+        if len(vel) != m:
+            raise ValueError('There must be an equal number of dependent '
+                             'speeds and velocity constraints.')
+        if acc and (len(acc) != m):
+            raise ValueError('There must be an equal number of dependent '
+                             'speeds and acceleration constraints.')
+        if vel:
+            u_zero = dict.fromkeys(self.u, 0)
+            udot_zero = dict.fromkeys(self._udot, 0)
+
+            # When calling kanes_equations, another class instance will be
+            # created if auxiliary u's are present. In this case, the
+            # computation of kinetic differential equation matrices will be
+            # skipped as this was computed during the original KanesMethod
+            # object, and the qd_u_map will not be available.
+            if self._qdot_u_map is not None:
+                vel = msubs(vel, self._qdot_u_map)
+
+            self._f_nh = msubs(vel, u_zero)
+            self._k_nh = (vel - self._f_nh).jacobian(self.u)
+            # If no acceleration constraints given, calculate them.
+            if not acc:
+                _f_dnh = (self._k_nh.diff(dynamicsymbols._t) * self.u +
+                          self._f_nh.diff(dynamicsymbols._t))
+                if self._qdot_u_map is not None:
+                    _f_dnh = msubs(_f_dnh, self._qdot_u_map)
+                self._f_dnh = _f_dnh
+                self._k_dnh = self._k_nh
+            else:
+                if self._qdot_u_map is not None:
+                    acc = msubs(acc, self._qdot_u_map)
+                self._f_dnh = msubs(acc, udot_zero)
+                self._k_dnh = (acc - self._f_dnh).jacobian(self._udot)
+
+            # Form of non-holonomic constraints is B*u + C = 0.
+            # We partition B into independent and dependent columns:
+            # Ars is then -B_dep.inv() * B_ind, and it relates dependent speeds
+            # to independent speeds as: udep = Ars*uind, neglecting the C term.
+            B_ind = self._k_nh[:, :p]
+            B_dep = self._k_nh[:, p:o]
+            self._Ars = -linear_solver(B_dep, B_ind)
+        else:
+            self._f_nh = Matrix()
+            self._k_nh = Matrix()
+            self._f_dnh = Matrix()
+            self._k_dnh = Matrix()
+            self._Ars = Matrix()
+
+    def _initialize_kindiffeq_matrices(self, kdeqs, linear_solver='LU'):
+        """Initialize the kinematic differential equation matrices.
+
+        Parameters
+        ==========
+        kdeqs : sequence of sympy expressions
+            Kinematic differential equations in the form of f(u,q',q,t) where
+            f() = 0. The equations have to be linear in the generalized
+            coordinates and generalized speeds.
+
+        """
+        linear_solver = _parse_linear_solver(linear_solver)
+        if kdeqs:
+            if len(self.q) != len(kdeqs):
+                raise ValueError('There must be an equal number of kinematic '
+                                 'differential equations and coordinates.')
+
+            u = self.u
+            qdot = self._qdot
+
+            kdeqs = Matrix(kdeqs)
+
+            u_zero = dict.fromkeys(u, 0)
+            uaux_zero = dict.fromkeys(self._uaux, 0)
+            qdot_zero = dict.fromkeys(qdot, 0)
+
+            # Extract the linear coefficient matrices as per the following
+            # equation:
+            #
+            # k_ku(q,t)*u(t) + k_kqdot(q,t)*q'(t) + f_k(q,t) = 0
+            #
+            k_ku = kdeqs.jacobian(u)
+            k_kqdot = kdeqs.jacobian(qdot)
+            f_k = kdeqs.xreplace(u_zero).xreplace(qdot_zero)
+
+            # The kinematic differential equations should be linear in both q'
+            # and u, so check for u and q' in the components.
+            dy_syms = find_dynamicsymbols(k_ku.row_join(k_kqdot).row_join(f_k))
+            nonlin_vars = [vari for vari in u[:] + qdot[:] if vari in dy_syms]
+            if nonlin_vars:
+                msg = ('The provided kinematic differential equations are '
+                       'nonlinear in {}. They must be linear in the '
+                       'generalized speeds and derivatives of the generalized '
+                       'coordinates.')
+                raise ValueError(msg.format(nonlin_vars))
+
+            self._f_k_implicit = f_k.xreplace(uaux_zero)
+            self._k_ku_implicit = k_ku.xreplace(uaux_zero)
+            self._k_kqdot_implicit = k_kqdot
+
+            # Solve for q'(t) such that the coefficient matrices are now in
+            # this form:
+            #
+            # k_kqdot^-1*k_ku*u(t) + I*q'(t) + k_kqdot^-1*f_k = 0
+            #
+            # NOTE : Solving the kinematic differential equations here is not
+            # necessary and prevents the equations from being provided in fully
+            # implicit form.
+            f_k_explicit = linear_solver(k_kqdot, f_k)
+            k_ku_explicit = linear_solver(k_kqdot, k_ku)
+            self._qdot_u_map = dict(zip(qdot, -(k_ku_explicit*u + f_k_explicit)))
+
+            self._f_k = f_k_explicit.xreplace(uaux_zero)
+            self._k_ku = k_ku_explicit.xreplace(uaux_zero)
+            self._k_kqdot = eye(len(qdot))
+
+        else:
+            self._qdot_u_map = None
+            self._f_k_implicit = self._f_k = Matrix()
+            self._k_ku_implicit = self._k_ku = Matrix()
+            self._k_kqdot_implicit = self._k_kqdot = Matrix()
+
+    def _form_fr(self, fl):
+        """Form the generalized active force."""
+        if fl is not None and (len(fl) == 0 or not iterable(fl)):
+            raise ValueError('Force pairs must be supplied in an '
+                'non-empty iterable or None.')
+
+        N = self._inertial
+        # pull out relevant velocities for constructing partial velocities
+        vel_list, f_list = _f_list_parser(fl, N)
+        vel_list = [msubs(i, self._qdot_u_map) for i in vel_list]
+        f_list = [msubs(i, self._qdot_u_map) for i in f_list]
+
+        # Fill Fr with dot product of partial velocities and forces
+        o = len(self.u)
+        b = len(f_list)
+        FR = zeros(o, 1)
+        partials = partial_velocity(vel_list, self.u, N)
+        for i in range(o):
+            FR[i] = sum(partials[j][i].dot(f_list[j]) for j in range(b))
+
+        # In case there are dependent speeds
+        if self._udep:
+            p = o - len(self._udep)
+            FRtilde = FR[:p, 0]
+            FRold = FR[p:o, 0]
+            FRtilde += self._Ars.T * FRold
+            FR = FRtilde
+
+        self._forcelist = fl
+        self._fr = FR
+        return FR
+
+    def _form_frstar(self, bl):
+        """Form the generalized inertia force."""
+
+        if not iterable(bl):
+            raise TypeError('Bodies must be supplied in an iterable.')
+
+        t = dynamicsymbols._t
+        N = self._inertial
+        # Dicts setting things to zero
+        udot_zero = dict.fromkeys(self._udot, 0)
+        uaux_zero = dict.fromkeys(self._uaux, 0)
+        uauxdot = [diff(i, t) for i in self._uaux]
+        uauxdot_zero = dict.fromkeys(uauxdot, 0)
+        # Dictionary of q' and q'' to u and u'
+        q_ddot_u_map = {k.diff(t): v.diff(t).xreplace(
+            self._qdot_u_map) for (k, v) in self._qdot_u_map.items()}
+        q_ddot_u_map.update(self._qdot_u_map)
+
+        # Fill up the list of partials: format is a list with num elements
+        # equal to number of entries in body list. Each of these elements is a
+        # list - either of length 1 for the translational components of
+        # particles or of length 2 for the translational and rotational
+        # components of rigid bodies. The inner most list is the list of
+        # partial velocities.
+        def get_partial_velocity(body):
+            if isinstance(body, RigidBody):
+                vlist = [body.masscenter.vel(N), body.frame.ang_vel_in(N)]
+            elif isinstance(body, Particle):
+                vlist = [body.point.vel(N),]
+            else:
+                raise TypeError('The body list may only contain either '
+                                'RigidBody or Particle as list elements.')
+            v = [msubs(vel, self._qdot_u_map) for vel in vlist]
+            return partial_velocity(v, self.u, N)
+        partials = [get_partial_velocity(body) for body in bl]
+
+        # Compute fr_star in two components:
+        # fr_star = -(MM*u' + nonMM)
+        o = len(self.u)
+        MM = zeros(o, o)
+        nonMM = zeros(o, 1)
+        zero_uaux = lambda expr: msubs(expr, uaux_zero)
+        zero_udot_uaux = lambda expr: msubs(msubs(expr, udot_zero), uaux_zero)
+        for i, body in enumerate(bl):
+            if isinstance(body, RigidBody):
+                M = zero_uaux(body.mass)
+                I = zero_uaux(body.central_inertia)
+                vel = zero_uaux(body.masscenter.vel(N))
+                omega = zero_uaux(body.frame.ang_vel_in(N))
+                acc = zero_udot_uaux(body.masscenter.acc(N))
+                inertial_force = (M.diff(t) * vel + M * acc)
+                inertial_torque = zero_uaux((I.dt(body.frame).dot(omega)) +
+                    msubs(I.dot(body.frame.ang_acc_in(N)), udot_zero) +
+                    (omega.cross(I.dot(omega))))
+                for j in range(o):
+                    tmp_vel = zero_uaux(partials[i][0][j])
+                    tmp_ang = zero_uaux(I.dot(partials[i][1][j]))
+                    for k in range(o):
+                        # translational
+                        MM[j, k] += M*tmp_vel.dot(partials[i][0][k])
+                        # rotational
+                        MM[j, k] += tmp_ang.dot(partials[i][1][k])
+                    nonMM[j] += inertial_force.dot(partials[i][0][j])
+                    nonMM[j] += inertial_torque.dot(partials[i][1][j])
+            else:
+                M = zero_uaux(body.mass)
+                vel = zero_uaux(body.point.vel(N))
+                acc = zero_udot_uaux(body.point.acc(N))
+                inertial_force = (M.diff(t) * vel + M * acc)
+                for j in range(o):
+                    temp = zero_uaux(partials[i][0][j])
+                    for k in range(o):
+                        MM[j, k] += M*temp.dot(partials[i][0][k])
+                    nonMM[j] += inertial_force.dot(partials[i][0][j])
+        # Compose fr_star out of MM and nonMM
+        MM = zero_uaux(msubs(MM, q_ddot_u_map))
+        nonMM = msubs(msubs(nonMM, q_ddot_u_map),
+                udot_zero, uauxdot_zero, uaux_zero)
+        fr_star = -(MM * msubs(Matrix(self._udot), uauxdot_zero) + nonMM)
+
+        # If there are dependent speeds, we need to find fr_star_tilde
+        if self._udep:
+            p = o - len(self._udep)
+            fr_star_ind = fr_star[:p, 0]
+            fr_star_dep = fr_star[p:o, 0]
+            fr_star = fr_star_ind + (self._Ars.T * fr_star_dep)
+            # Apply the same to MM
+            MMi = MM[:p, :]
+            MMd = MM[p:o, :]
+            MM = MMi + (self._Ars.T * MMd)
+            # Apply the same to nonMM
+            nonMM = nonMM[:p, :] + (self._Ars.T * nonMM[p:o, :])
+
+        self._bodylist = bl
+        self._frstar = fr_star
+        self._k_d = MM
+        self._f_d = -(self._fr - nonMM)
+        return fr_star
+
+    def to_linearizer(self, linear_solver='LU'):
+        """Returns an instance of the Linearizer class, initiated from the
+        data in the KanesMethod class. This may be more desirable than using
+        the linearize class method, as the Linearizer object will allow more
+        efficient recalculation (i.e. about varying operating points).
+
+        Parameters
+        ==========
+        linear_solver : str, callable
+            Method used to solve the several symbolic linear systems of the
+            form ``A*x=b`` in the linearization process. If a string is
+            supplied, it should be a valid method that can be used with the
+            :meth:`sympy.matrices.matrixbase.MatrixBase.solve`. If a callable is
+            supplied, it should have the format ``x = f(A, b)``, where it
+            solves the equations and returns the solution. The default is
+            ``'LU'`` which corresponds to SymPy's ``A.LUsolve(b)``.
+            ``LUsolve()`` is fast to compute but will often result in
+            divide-by-zero and thus ``nan`` results.
+
+        Returns
+        =======
+        Linearizer
+            An instantiated
+            :class:`sympy.physics.mechanics.linearize.Linearizer`.
+
+        """
+
+        if (self._fr is None) or (self._frstar is None):
+            raise ValueError('Need to compute Fr, Fr* first.')
+
+        # Get required equation components. The Kane's method class breaks
+        # these into pieces. Need to reassemble
+        f_c = self._f_h
+        if self._f_nh and self._k_nh:
+            f_v = self._f_nh + self._k_nh*Matrix(self.u)
+        else:
+            f_v = Matrix()
+        if self._f_dnh and self._k_dnh:
+            f_a = self._f_dnh + self._k_dnh*Matrix(self._udot)
+        else:
+            f_a = Matrix()
+        # Dicts to sub to zero, for splitting up expressions
+        u_zero = dict.fromkeys(self.u, 0)
+        ud_zero = dict.fromkeys(self._udot, 0)
+        qd_zero = dict.fromkeys(self._qdot, 0)
+        qd_u_zero = dict.fromkeys(Matrix([self._qdot, self.u]), 0)
+        # Break the kinematic differential eqs apart into f_0 and f_1
+        f_0 = msubs(self._f_k, u_zero) + self._k_kqdot*Matrix(self._qdot)
+        f_1 = msubs(self._f_k, qd_zero) + self._k_ku*Matrix(self.u)
+        # Break the dynamic differential eqs into f_2 and f_3
+        f_2 = msubs(self._frstar, qd_u_zero)
+        f_3 = msubs(self._frstar, ud_zero) + self._fr
+        f_4 = zeros(len(f_2), 1)
+
+        # Get the required vector components
+        q = self.q
+        u = self.u
+        if self._qdep:
+            q_i = q[:-len(self._qdep)]
+        else:
+            q_i = q
+        q_d = self._qdep
+        if self._udep:
+            u_i = u[:-len(self._udep)]
+        else:
+            u_i = u
+        u_d = self._udep
+
+        # Form dictionary to set auxiliary speeds & their derivatives to 0.
+        uaux = self._uaux
+        uauxdot = uaux.diff(dynamicsymbols._t)
+        uaux_zero = dict.fromkeys(Matrix([uaux, uauxdot]), 0)
+
+        # Checking for dynamic symbols outside the dynamic differential
+        # equations; throws error if there is.
+        sym_list = set(Matrix([q, self._qdot, u, self._udot, uaux, uauxdot]))
+        if any(find_dynamicsymbols(i, sym_list) for i in [self._k_kqdot,
+                self._k_ku, self._f_k, self._k_dnh, self._f_dnh, self._k_d]):
+            raise ValueError('Cannot have dynamicsymbols outside dynamic \
+                             forcing vector.')
+
+        # Find all other dynamic symbols, forming the forcing vector r.
+        # Sort r to make it canonical.
+        r = list(find_dynamicsymbols(msubs(self._f_d, uaux_zero), sym_list))
+        r.sort(key=default_sort_key)
+
+        # Check for any derivatives of variables in r that are also found in r.
+        for i in r:
+            if diff(i, dynamicsymbols._t) in r:
+                raise ValueError('Cannot have derivatives of specified \
+                                 quantities when linearizing forcing terms.')
+        return Linearizer(f_0, f_1, f_2, f_3, f_4, f_c, f_v, f_a, q, u, q_i,
+                q_d, u_i, u_d, r, linear_solver=linear_solver)
+
+    # TODO : Remove `new_method` after 1.1 has been released.
+    def linearize(self, *, new_method=None, linear_solver='LU', **kwargs):
+        """ Linearize the equations of motion about a symbolic operating point.
+
+        Parameters
+        ==========
+        new_method
+            Deprecated, does nothing and will be removed.
+        linear_solver : str, callable
+            Method used to solve the several symbolic linear systems of the
+            form ``A*x=b`` in the linearization process. If a string is
+            supplied, it should be a valid method that can be used with the
+            :meth:`sympy.matrices.matrixbase.MatrixBase.solve`. If a callable is
+            supplied, it should have the format ``x = f(A, b)``, where it
+            solves the equations and returns the solution. The default is
+            ``'LU'`` which corresponds to SymPy's ``A.LUsolve(b)``.
+            ``LUsolve()`` is fast to compute but will often result in
+            divide-by-zero and thus ``nan`` results.
+        **kwargs
+            Extra keyword arguments are passed to
+            :meth:`sympy.physics.mechanics.linearize.Linearizer.linearize`.
+
+        Explanation
+        ===========
+
+        If kwarg A_and_B is False (default), returns M, A, B, r for the
+        linearized form, M*[q', u']^T = A*[q_ind, u_ind]^T + B*r.
+
+        If kwarg A_and_B is True, returns A, B, r for the linearized form
+        dx = A*x + B*r, where x = [q_ind, u_ind]^T. Note that this is
+        computationally intensive if there are many symbolic parameters. For
+        this reason, it may be more desirable to use the default A_and_B=False,
+        returning M, A, and B. Values may then be substituted in to these
+        matrices, and the state space form found as
+        A = P.T*M.inv()*A, B = P.T*M.inv()*B, where P = Linearizer.perm_mat.
+
+        In both cases, r is found as all dynamicsymbols in the equations of
+        motion that are not part of q, u, q', or u'. They are sorted in
+        canonical form.
+
+        The operating points may be also entered using the ``op_point`` kwarg.
+        This takes a dictionary of {symbol: value}, or a an iterable of such
+        dictionaries. The values may be numeric or symbolic. The more values
+        you can specify beforehand, the faster this computation will run.
+
+        For more documentation, please see the ``Linearizer`` class.
+
+        """
+
+        linearizer = self.to_linearizer(linear_solver=linear_solver)
+        result = linearizer.linearize(**kwargs)
+        return result + (linearizer.r,)
+
+    def kanes_equations(self, bodies=None, loads=None):
+        """ Method to form Kane's equations, Fr + Fr* = 0.
+
+        Explanation
+        ===========
+
+        Returns (Fr, Fr*). In the case where auxiliary generalized speeds are
+        present (say, s auxiliary speeds, o generalized speeds, and m motion
+        constraints) the length of the returned vectors will be o - m + s in
+        length. The first o - m equations will be the constrained Kane's
+        equations, then the s auxiliary Kane's equations. These auxiliary
+        equations can be accessed with the auxiliary_eqs property.
+
+        Parameters
+        ==========
+
+        bodies : iterable
+            An iterable of all RigidBody's and Particle's in the system.
+            A system must have at least one body.
+        loads : iterable
+            Takes in an iterable of (Particle, Vector) or (ReferenceFrame, Vector)
+            tuples which represent the force at a point or torque on a frame.
+            Must be either a non-empty iterable of tuples or None which corresponds
+            to a system with no constraints.
+        """
+        if bodies is None:
+            bodies = self.bodies
+        if  loads is None and self._forcelist is not None:
+            loads = self._forcelist
+        if loads == []:
+            loads = None
+        if not self._k_kqdot:
+            raise AttributeError('Create an instance of KanesMethod with '
+                    'kinematic differential equations to use this method.')
+        fr = self._form_fr(loads)
+        frstar = self._form_frstar(bodies)
+        if self._uaux:
+            if not self._udep:
+                km = KanesMethod(self._inertial, self.q, self._uaux,
+                             u_auxiliary=self._uaux, constraint_solver=self._constraint_solver)
+            else:
+                km = KanesMethod(self._inertial, self.q, self._uaux,
+                        u_auxiliary=self._uaux, u_dependent=self._udep,
+                        velocity_constraints=(self._k_nh * self.u +
+                        self._f_nh),
+                        acceleration_constraints=(self._k_dnh * self._udot +
+                        self._f_dnh),
+                        constraint_solver=self._constraint_solver
+                        )
+            km._qdot_u_map = self._qdot_u_map
+            self._km = km
+            fraux = km._form_fr(loads)
+            frstaraux = km._form_frstar(bodies)
+            self._aux_eq = fraux + frstaraux
+            self._fr = fr.col_join(fraux)
+            self._frstar = frstar.col_join(frstaraux)
+        return (self._fr, self._frstar)
+
+    def _form_eoms(self):
+        fr, frstar = self.kanes_equations(self.bodylist, self.forcelist)
+        return fr + frstar
+
+    def rhs(self, inv_method=None):
+        """Returns the system's equations of motion in first order form. The
+        output is the right hand side of::
+
+           x' = |q'| =: f(q, u, r, p, t)
+                |u'|
+
+        The right hand side is what is needed by most numerical ODE
+        integrators.
+
+        Parameters
+        ==========
+
+        inv_method : str
+            The specific sympy inverse matrix calculation method to use. For a
+            list of valid methods, see
+            :meth:`~sympy.matrices.matrixbase.MatrixBase.inv`
+
+        """
+        rhs = zeros(len(self.q) + len(self.u), 1)
+        kdes = self.kindiffdict()
+        for i, q_i in enumerate(self.q):
+            rhs[i] = kdes[q_i.diff()]
+
+        if inv_method is None:
+            rhs[len(self.q):, 0] = self.mass_matrix.LUsolve(self.forcing)
+        else:
+            rhs[len(self.q):, 0] = (self.mass_matrix.inv(inv_method,
+                                                         try_block_diag=True) *
+                                    self.forcing)
+
+        return rhs
+
+    def kindiffdict(self):
+        """Returns a dictionary mapping q' to u."""
+        if not self._qdot_u_map:
+            raise AttributeError('Create an instance of KanesMethod with '
+                    'kinematic differential equations to use this method.')
+        return self._qdot_u_map
+
+    @property
+    def auxiliary_eqs(self):
+        """A matrix containing the auxiliary equations."""
+        if not self._fr or not self._frstar:
+            raise ValueError('Need to compute Fr, Fr* first.')
+        if not self._uaux:
+            raise ValueError('No auxiliary speeds have been declared.')
+        return self._aux_eq
+
+    @property
+    def mass_matrix_kin(self):
+        r"""The kinematic "mass matrix" $\mathbf{k_{k\dot{q}}}$ of the system."""
+        return self._k_kqdot if self.explicit_kinematics else self._k_kqdot_implicit
+
+    @property
+    def forcing_kin(self):
+        """The kinematic "forcing vector" of the system."""
+        if self.explicit_kinematics:
+            return -(self._k_ku * Matrix(self.u) + self._f_k)
+        else:
+            return -(self._k_ku_implicit * Matrix(self.u) + self._f_k_implicit)
+
+    @property
+    def mass_matrix(self):
+        """The mass matrix of the system."""
+        if not self._fr or not self._frstar:
+            raise ValueError('Need to compute Fr, Fr* first.')
+        return Matrix([self._k_d, self._k_dnh])
+
+    @property
+    def forcing(self):
+        """The forcing vector of the system."""
+        if not self._fr or not self._frstar:
+            raise ValueError('Need to compute Fr, Fr* first.')
+        return -Matrix([self._f_d, self._f_dnh])
+
+    @property
+    def mass_matrix_full(self):
+        """The mass matrix of the system, augmented by the kinematic
+        differential equations in explicit or implicit form."""
+        if not self._fr or not self._frstar:
+            raise ValueError('Need to compute Fr, Fr* first.')
+        o, n = len(self.u), len(self.q)
+        return (self.mass_matrix_kin.row_join(zeros(n, o))).col_join(
+            zeros(o, n).row_join(self.mass_matrix))
+
+    @property
+    def forcing_full(self):
+        """The forcing vector of the system, augmented by the kinematic
+        differential equations in explicit or implicit form."""
+        return Matrix([self.forcing_kin, self.forcing])
+
+    @property
+    def q(self):
+        return self._q
+
+    @property
+    def u(self):
+        return self._u
+
+    @property
+    def bodylist(self):
+        return self._bodylist
+
+    @property
+    def forcelist(self):
+        return self._forcelist
+
+    @property
+    def bodies(self):
+        return self._bodylist
+
+    @property
+    def loads(self):
+        return self._forcelist

lib/python3.12/site-packages/sympy/physics/mechanics/linearize.py

@@ -0,0 +1,474 @@
+__all__ = ['Linearizer']
+
+from sympy import Matrix, eye, zeros
+from sympy.core.symbol import Dummy
+from sympy.utilities.iterables import flatten
+from sympy.physics.vector import dynamicsymbols
+from sympy.physics.mechanics.functions import msubs, _parse_linear_solver
+
+from collections import namedtuple
+from collections.abc import Iterable
+
+
+class Linearizer:
+    """This object holds the general model form for a dynamic system. This
+    model is used for computing the linearized form of the system, while
+    properly dealing with constraints leading to  dependent coordinates and
+    speeds. The notation and method is described in [1]_.
+
+    Attributes
+    ==========
+
+    f_0, f_1, f_2, f_3, f_4, f_c, f_v, f_a : Matrix
+        Matrices holding the general system form.
+    q, u, r : Matrix
+        Matrices holding the generalized coordinates, speeds, and
+        input vectors.
+    q_i, u_i : Matrix
+        Matrices of the independent generalized coordinates and speeds.
+    q_d, u_d : Matrix
+        Matrices of the dependent generalized coordinates and speeds.
+    perm_mat : Matrix
+        Permutation matrix such that [q_ind, u_ind]^T = perm_mat*[q, u]^T
+
+    References
+    ==========
+
+    .. [1] D. L. Peterson, G. Gede, and M. Hubbard, "Symbolic linearization of
+           equations of motion of constrained multibody systems," Multibody
+           Syst Dyn, vol. 33, no. 2, pp. 143-161, Feb. 2015, doi:
+           10.1007/s11044-014-9436-5.
+
+    """
+
+    def __init__(self, f_0, f_1, f_2, f_3, f_4, f_c, f_v, f_a, q, u, q_i=None,
+                 q_d=None, u_i=None, u_d=None, r=None, lams=None,
+                 linear_solver='LU'):
+        """
+        Parameters
+        ==========
+
+        f_0, f_1, f_2, f_3, f_4, f_c, f_v, f_a : array_like
+            System of equations holding the general system form.
+            Supply empty array or Matrix if the parameter
+            does not exist.
+        q : array_like
+            The generalized coordinates.
+        u : array_like
+            The generalized speeds
+        q_i, u_i : array_like, optional
+            The independent generalized coordinates and speeds.
+        q_d, u_d : array_like, optional
+            The dependent generalized coordinates and speeds.
+        r : array_like, optional
+            The input variables.
+        lams : array_like, optional
+            The lagrange multipliers
+        linear_solver : str, callable
+            Method used to solve the several symbolic linear systems of the
+            form ``A*x=b`` in the linearization process. If a string is
+            supplied, it should be a valid method that can be used with the
+            :meth:`sympy.matrices.matrixbase.MatrixBase.solve`. If a callable is
+            supplied, it should have the format ``x = f(A, b)``, where it
+            solves the equations and returns the solution. The default is
+            ``'LU'`` which corresponds to SymPy's ``A.LUsolve(b)``.
+            ``LUsolve()`` is fast to compute but will often result in
+            divide-by-zero and thus ``nan`` results.
+
+        """
+        self.linear_solver = _parse_linear_solver(linear_solver)
+
+        # Generalized equation form
+        self.f_0 = Matrix(f_0)
+        self.f_1 = Matrix(f_1)
+        self.f_2 = Matrix(f_2)
+        self.f_3 = Matrix(f_3)
+        self.f_4 = Matrix(f_4)
+        self.f_c = Matrix(f_c)
+        self.f_v = Matrix(f_v)
+        self.f_a = Matrix(f_a)
+
+        # Generalized equation variables
+        self.q = Matrix(q)
+        self.u = Matrix(u)
+        none_handler = lambda x: Matrix(x) if x else Matrix()
+        self.q_i = none_handler(q_i)
+        self.q_d = none_handler(q_d)
+        self.u_i = none_handler(u_i)
+        self.u_d = none_handler(u_d)
+        self.r = none_handler(r)
+        self.lams = none_handler(lams)
+
+        # Derivatives of generalized equation variables
+        self._qd = self.q.diff(dynamicsymbols._t)
+        self._ud = self.u.diff(dynamicsymbols._t)
+        # If the user doesn't actually use generalized variables, and the
+        # qd and u vectors have any intersecting variables, this can cause
+        # problems. We'll fix this with some hackery, and Dummy variables
+        dup_vars = set(self._qd).intersection(self.u)
+        self._qd_dup = Matrix([var if var not in dup_vars else Dummy() for var
+                               in self._qd])
+
+        # Derive dimesion terms
+        l = len(self.f_c)
+        m = len(self.f_v)
+        n = len(self.q)
+        o = len(self.u)
+        s = len(self.r)
+        k = len(self.lams)
+        dims = namedtuple('dims', ['l', 'm', 'n', 'o', 's', 'k'])
+        self._dims = dims(l, m, n, o, s, k)
+
+        self._Pq = None
+        self._Pqi = None
+        self._Pqd = None
+        self._Pu = None
+        self._Pui = None
+        self._Pud = None
+        self._C_0 = None
+        self._C_1 = None
+        self._C_2 = None
+        self.perm_mat = None
+
+        self._setup_done = False
+
+    def _setup(self):
+        # Calculations here only need to be run once. They are moved out of
+        # the __init__ method to increase the speed of Linearizer creation.
+        self._form_permutation_matrices()
+        self._form_block_matrices()
+        self._form_coefficient_matrices()
+        self._setup_done = True
+
+    def _form_permutation_matrices(self):
+        """Form the permutation matrices Pq and Pu."""
+
+        # Extract dimension variables
+        l, m, n, o, s, k = self._dims
+        # Compute permutation matrices
+        if n != 0:
+            self._Pq = permutation_matrix(self.q, Matrix([self.q_i, self.q_d]))
+            if l > 0:
+                self._Pqi = self._Pq[:, :-l]
+                self._Pqd = self._Pq[:, -l:]
+            else:
+                self._Pqi = self._Pq
+                self._Pqd = Matrix()
+        if o != 0:
+            self._Pu = permutation_matrix(self.u, Matrix([self.u_i, self.u_d]))
+            if m > 0:
+                self._Pui = self._Pu[:, :-m]
+                self._Pud = self._Pu[:, -m:]
+            else:
+                self._Pui = self._Pu
+                self._Pud = Matrix()
+        # Compute combination permutation matrix for computing A and B
+        P_col1 = Matrix([self._Pqi, zeros(o + k, n - l)])
+        P_col2 = Matrix([zeros(n, o - m), self._Pui, zeros(k, o - m)])
+        if P_col1:
+            if P_col2:
+                self.perm_mat = P_col1.row_join(P_col2)
+            else:
+                self.perm_mat = P_col1
+        else:
+            self.perm_mat = P_col2
+
+    def _form_coefficient_matrices(self):
+        """Form the coefficient matrices C_0, C_1, and C_2."""
+
+        # Extract dimension variables
+        l, m, n, o, s, k = self._dims
+        # Build up the coefficient matrices C_0, C_1, and C_2
+        # If there are configuration constraints (l > 0), form C_0 as normal.
+        # If not, C_0 is I_(nxn). Note that this works even if n=0
+        if l > 0:
+            f_c_jac_q = self.f_c.jacobian(self.q)
+            self._C_0 = (eye(n) - self._Pqd *
+                         self.linear_solver(f_c_jac_q*self._Pqd,
+                                            f_c_jac_q))*self._Pqi
+        else:
+            self._C_0 = eye(n)
+        # If there are motion constraints (m > 0), form C_1 and C_2 as normal.
+        # If not, C_1 is 0, and C_2 is I_(oxo). Note that this works even if
+        # o = 0.
+        if m > 0:
+            f_v_jac_u = self.f_v.jacobian(self.u)
+            temp = f_v_jac_u * self._Pud
+            if n != 0:
+                f_v_jac_q = self.f_v.jacobian(self.q)
+                self._C_1 = -self._Pud * self.linear_solver(temp, f_v_jac_q)
+            else:
+                self._C_1 = zeros(o, n)
+            self._C_2 = (eye(o) - self._Pud *
+                         self.linear_solver(temp, f_v_jac_u))*self._Pui
+        else:
+            self._C_1 = zeros(o, n)
+            self._C_2 = eye(o)
+
+    def _form_block_matrices(self):
+        """Form the block matrices for composing M, A, and B."""
+
+        # Extract dimension variables
+        l, m, n, o, s, k = self._dims
+        # Block Matrix Definitions. These are only defined if under certain
+        # conditions. If undefined, an empty matrix is used instead
+        if n != 0:
+            self._M_qq = self.f_0.jacobian(self._qd)
+            self._A_qq = -(self.f_0 + self.f_1).jacobian(self.q)
+        else:
+            self._M_qq = Matrix()
+            self._A_qq = Matrix()
+        if n != 0 and m != 0:
+            self._M_uqc = self.f_a.jacobian(self._qd_dup)
+            self._A_uqc = -self.f_a.jacobian(self.q)
+        else:
+            self._M_uqc = Matrix()
+            self._A_uqc = Matrix()
+        if n != 0 and o - m + k != 0:
+            self._M_uqd = self.f_3.jacobian(self._qd_dup)
+            self._A_uqd = -(self.f_2 + self.f_3 + self.f_4).jacobian(self.q)
+        else:
+            self._M_uqd = Matrix()
+            self._A_uqd = Matrix()
+        if o != 0 and m != 0:
+            self._M_uuc = self.f_a.jacobian(self._ud)
+            self._A_uuc = -self.f_a.jacobian(self.u)
+        else:
+            self._M_uuc = Matrix()
+            self._A_uuc = Matrix()
+        if o != 0 and o - m + k != 0:
+            self._M_uud = self.f_2.jacobian(self._ud)
+            self._A_uud = -(self.f_2 + self.f_3).jacobian(self.u)
+        else:
+            self._M_uud = Matrix()
+            self._A_uud = Matrix()
+        if o != 0 and n != 0:
+            self._A_qu = -self.f_1.jacobian(self.u)
+        else:
+            self._A_qu = Matrix()
+        if k != 0 and o - m + k != 0:
+            self._M_uld = self.f_4.jacobian(self.lams)
+        else:
+            self._M_uld = Matrix()
+        if s != 0 and o - m + k != 0:
+            self._B_u = -self.f_3.jacobian(self.r)
+        else:
+            self._B_u = Matrix()
+
+    def linearize(self, op_point=None, A_and_B=False, simplify=False):
+        """Linearize the system about the operating point. Note that
+        q_op, u_op, qd_op, ud_op must satisfy the equations of motion.
+        These may be either symbolic or numeric.
+
+        Parameters
+        ==========
+        op_point : dict or iterable of dicts, optional
+            Dictionary or iterable of dictionaries containing the operating
+            point conditions for all or a subset of the generalized
+            coordinates, generalized speeds, and time derivatives of the
+            generalized speeds. These will be substituted into the linearized
+            system before the linearization is complete. Leave set to ``None``
+            if you want the operating point to be an arbitrary set of symbols.
+            Note that any reduction in symbols (whether substituted for numbers
+            or expressions with a common parameter) will result in faster
+            runtime.
+        A_and_B : bool, optional
+            If A_and_B=False (default), (M, A, B) is returned and of
+            A_and_B=True, (A, B) is returned. See below.
+        simplify : bool, optional
+            Determines if returned values are simplified before return.
+            For large expressions this may be time consuming. Default is False.
+
+        Returns
+        =======
+        M, A, B : Matrices, ``A_and_B=False``
+            Matrices from the implicit form:
+                ``[M]*[q', u']^T = [A]*[q_ind, u_ind]^T + [B]*r``
+        A, B : Matrices, ``A_and_B=True``
+            Matrices from the explicit form:
+                ``[q_ind', u_ind']^T = [A]*[q_ind, u_ind]^T + [B]*r``
+
+        Notes
+        =====
+
+        Note that the process of solving with A_and_B=True is computationally
+        intensive if there are many symbolic parameters. For this reason, it
+        may be more desirable to use the default A_and_B=False, returning M, A,
+        and B. More values may then be substituted in to these matrices later
+        on. The state space form can then be found as A = P.T*M.LUsolve(A), B =
+        P.T*M.LUsolve(B), where P = Linearizer.perm_mat.
+
+        """
+
+        # Run the setup if needed:
+        if not self._setup_done:
+            self._setup()
+
+        # Compose dict of operating conditions
+        if isinstance(op_point, dict):
+            op_point_dict = op_point
+        elif isinstance(op_point, Iterable):
+            op_point_dict = {}
+            for op in op_point:
+                op_point_dict.update(op)
+        else:
+            op_point_dict = {}
+
+        # Extract dimension variables
+        l, m, n, o, s, k = self._dims
+
+        # Rename terms to shorten expressions
+        M_qq = self._M_qq
+        M_uqc = self._M_uqc
+        M_uqd = self._M_uqd
+        M_uuc = self._M_uuc
+        M_uud = self._M_uud
+        M_uld = self._M_uld
+        A_qq = self._A_qq
+        A_uqc = self._A_uqc
+        A_uqd = self._A_uqd
+        A_qu = self._A_qu
+        A_uuc = self._A_uuc
+        A_uud = self._A_uud
+        B_u = self._B_u
+        C_0 = self._C_0
+        C_1 = self._C_1
+        C_2 = self._C_2
+
+        # Build up Mass Matrix
+        #     |M_qq    0_nxo   0_nxk|
+        # M = |M_uqc   M_uuc   0_mxk|
+        #     |M_uqd   M_uud   M_uld|
+        if o != 0:
+            col2 = Matrix([zeros(n, o), M_uuc, M_uud])
+        if k != 0:
+            col3 = Matrix([zeros(n + m, k), M_uld])
+        if n != 0:
+            col1 = Matrix([M_qq, M_uqc, M_uqd])
+            if o != 0 and k != 0:
+                M = col1.row_join(col2).row_join(col3)
+            elif o != 0:
+                M = col1.row_join(col2)
+            else:
+                M = col1
+        elif k != 0:
+            M = col2.row_join(col3)
+        else:
+            M = col2
+        M_eq = msubs(M, op_point_dict)
+
+        # Build up state coefficient matrix A
+        #     |(A_qq + A_qu*C_1)*C_0       A_qu*C_2|
+        # A = |(A_uqc + A_uuc*C_1)*C_0    A_uuc*C_2|
+        #     |(A_uqd + A_uud*C_1)*C_0    A_uud*C_2|
+        # Col 1 is only defined if n != 0
+        if n != 0:
+            r1c1 = A_qq
+            if o != 0:
+                r1c1 += (A_qu * C_1)
+            r1c1 = r1c1 * C_0
+            if m != 0:
+                r2c1 = A_uqc
+                if o != 0:
+                    r2c1 += (A_uuc * C_1)
+                r2c1 = r2c1 * C_0
+            else:
+                r2c1 = Matrix()
+            if o - m + k != 0:
+                r3c1 = A_uqd
+                if o != 0:
+                    r3c1 += (A_uud * C_1)
+                r3c1 = r3c1 * C_0
+            else:
+                r3c1 = Matrix()
+            col1 = Matrix([r1c1, r2c1, r3c1])
+        else:
+            col1 = Matrix()
+        # Col 2 is only defined if o != 0
+        if o != 0:
+            if n != 0:
+                r1c2 = A_qu * C_2
+            else:
+                r1c2 = Matrix()
+            if m != 0:
+                r2c2 = A_uuc * C_2
+            else:
+                r2c2 = Matrix()
+            if o - m + k != 0:
+                r3c2 = A_uud * C_2
+            else:
+                r3c2 = Matrix()
+            col2 = Matrix([r1c2, r2c2, r3c2])
+        else:
+            col2 = Matrix()
+        if col1:
+            if col2:
+                Amat = col1.row_join(col2)
+            else:
+                Amat = col1
+        else:
+            Amat = col2
+        Amat_eq = msubs(Amat, op_point_dict)
+
+        # Build up the B matrix if there are forcing variables
+        #     |0_(n + m)xs|
+        # B = |B_u        |
+        if s != 0 and o - m + k != 0:
+            Bmat = zeros(n + m, s).col_join(B_u)
+            Bmat_eq = msubs(Bmat, op_point_dict)
+        else:
+            Bmat_eq = Matrix()
+
+        # kwarg A_and_B indicates to return  A, B for forming the equation
+        # dx = [A]x + [B]r, where x = [q_indnd, u_indnd]^T,
+        if A_and_B:
+            A_cont = self.perm_mat.T * self.linear_solver(M_eq, Amat_eq)
+            if Bmat_eq:
+                B_cont = self.perm_mat.T * self.linear_solver(M_eq, Bmat_eq)
+            else:
+                # Bmat = Matrix([]), so no need to sub
+                B_cont = Bmat_eq
+            if simplify:
+                A_cont.simplify()
+                B_cont.simplify()
+            return A_cont, B_cont
+        # Otherwise return M, A, B for forming the equation
+        # [M]dx = [A]x + [B]r, where x = [q, u]^T
+        else:
+            if simplify:
+                M_eq.simplify()
+                Amat_eq.simplify()
+                Bmat_eq.simplify()
+            return M_eq, Amat_eq, Bmat_eq
+
+
+def permutation_matrix(orig_vec, per_vec):
+    """Compute the permutation matrix to change order of
+    orig_vec into order of per_vec.
+
+    Parameters
+    ==========
+
+    orig_vec : array_like
+        Symbols in original ordering.
+    per_vec : array_like
+        Symbols in new ordering.
+
+    Returns
+    =======
+
+    p_matrix : Matrix
+        Permutation matrix such that orig_vec == (p_matrix * per_vec).
+    """
+    if not isinstance(orig_vec, (list, tuple)):
+        orig_vec = flatten(orig_vec)
+    if not isinstance(per_vec, (list, tuple)):
+        per_vec = flatten(per_vec)
+    if set(orig_vec) != set(per_vec):
+        raise ValueError("orig_vec and per_vec must be the same length, "
+                         "and contain the same symbols.")
+    ind_list = [orig_vec.index(i) for i in per_vec]
+    p_matrix = zeros(len(orig_vec))
+    for i, j in enumerate(ind_list):
+        p_matrix[i, j] = 1
+    return p_matrix

lib/python3.12/site-packages/sympy/physics/mechanics/models.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python
+"""This module contains some sample symbolic models used for testing and
+examples."""
+
+# Internal imports
+from sympy.core import backend as sm
+import sympy.physics.mechanics as me
+
+
+def multi_mass_spring_damper(n=1, apply_gravity=False,
+                             apply_external_forces=False):
+    r"""Returns a system containing the symbolic equations of motion and
+    associated variables for a simple multi-degree of freedom point mass,
+    spring, damper system with optional gravitational and external
+    specified forces. For example, a two mass system under the influence of
+    gravity and external forces looks like:
+
+    ::
+
+        ----------------
+         |     |     |   | g
+         \    | |    |   V
+      k0 /    --- c0 |
+         |     |     | x0, v0
+        ---------    V
+        |  m0   | -----
+        ---------    |
+         | |   |     |
+         \ v  | |    |
+      k1 / f0 --- c1 |
+         |     |     | x1, v1
+        ---------    V
+        |  m1   | -----
+        ---------
+           | f1
+           V
+
+    Parameters
+    ==========
+
+    n : integer
+        The number of masses in the serial chain.
+    apply_gravity : boolean
+        If true, gravity will be applied to each mass.
+    apply_external_forces : boolean
+        If true, a time varying external force will be applied to each mass.
+
+    Returns
+    =======
+
+    kane : sympy.physics.mechanics.kane.KanesMethod
+        A KanesMethod object.
+
+    """
+
+    mass = sm.symbols('m:{}'.format(n))
+    stiffness = sm.symbols('k:{}'.format(n))
+    damping = sm.symbols('c:{}'.format(n))
+
+    acceleration_due_to_gravity = sm.symbols('g')
+
+    coordinates = me.dynamicsymbols('x:{}'.format(n))
+    speeds = me.dynamicsymbols('v:{}'.format(n))
+    specifieds = me.dynamicsymbols('f:{}'.format(n))
+
+    ceiling = me.ReferenceFrame('N')
+    origin = me.Point('origin')
+    origin.set_vel(ceiling, 0)
+
+    points = [origin]
+    kinematic_equations = []
+    particles = []
+    forces = []
+
+    for i in range(n):
+
+        center = points[-1].locatenew('center{}'.format(i),
+                                      coordinates[i] * ceiling.x)
+        center.set_vel(ceiling, points[-1].vel(ceiling) +
+                       speeds[i] * ceiling.x)
+        points.append(center)
+
+        block = me.Particle('block{}'.format(i), center, mass[i])
+
+        kinematic_equations.append(speeds[i] - coordinates[i].diff())
+
+        total_force = (-stiffness[i] * coordinates[i] -
+                       damping[i] * speeds[i])
+        try:
+            total_force += (stiffness[i + 1] * coordinates[i + 1] +
+                            damping[i + 1] * speeds[i + 1])
+        except IndexError:  # no force from below on last mass
+            pass
+
+        if apply_gravity:
+            total_force += mass[i] * acceleration_due_to_gravity
+
+        if apply_external_forces:
+            total_force += specifieds[i]
+
+        forces.append((center, total_force * ceiling.x))
+
+        particles.append(block)
+
+    kane = me.KanesMethod(ceiling, q_ind=coordinates, u_ind=speeds,
+                          kd_eqs=kinematic_equations)
+    kane.kanes_equations(particles, forces)
+
+    return kane
+
+
+def n_link_pendulum_on_cart(n=1, cart_force=True, joint_torques=False):
+    r"""Returns the system containing the symbolic first order equations of
+    motion for a 2D n-link pendulum on a sliding cart under the influence of
+    gravity.
+
+    ::
+
+                  |
+         o    y   v
+          \ 0 ^   g
+           \  |
+          --\-|----
+          |  \|   |
+      F-> |   o --|---> x
+          |       |
+          ---------
+           o     o
+
+    Parameters
+    ==========
+
+    n : integer
+        The number of links in the pendulum.
+    cart_force : boolean, default=True
+        If true an external specified lateral force is applied to the cart.
+    joint_torques : boolean, default=False
+        If true joint torques will be added as specified inputs at each
+        joint.
+
+    Returns
+    =======
+
+    kane : sympy.physics.mechanics.kane.KanesMethod
+        A KanesMethod object.
+
+    Notes
+    =====
+
+    The degrees of freedom of the system are n + 1, i.e. one for each
+    pendulum link and one for the lateral motion of the cart.
+
+    M x' = F, where x = [u0, ..., un+1, q0, ..., qn+1]
+
+    The joint angles are all defined relative to the ground where the x axis
+    defines the ground line and the y axis points up. The joint torques are
+    applied between each adjacent link and the between the cart and the
+    lower link where a positive torque corresponds to positive angle.
+
+    """
+    if n <= 0:
+        raise ValueError('The number of links must be a positive integer.')
+
+    q = me.dynamicsymbols('q:{}'.format(n + 1))
+    u = me.dynamicsymbols('u:{}'.format(n + 1))
+
+    if joint_torques is True:
+        T = me.dynamicsymbols('T1:{}'.format(n + 1))
+
+    m = sm.symbols('m:{}'.format(n + 1))
+    l = sm.symbols('l:{}'.format(n))
+    g, t = sm.symbols('g t')
+
+    I = me.ReferenceFrame('I')
+    O = me.Point('O')
+    O.set_vel(I, 0)
+
+    P0 = me.Point('P0')
+    P0.set_pos(O, q[0] * I.x)
+    P0.set_vel(I, u[0] * I.x)
+    Pa0 = me.Particle('Pa0', P0, m[0])
+
+    frames = [I]
+    points = [P0]
+    particles = [Pa0]
+    forces = [(P0, -m[0] * g * I.y)]
+    kindiffs = [q[0].diff(t) - u[0]]
+
+    if cart_force is True or joint_torques is True:
+        specified = []
+    else:
+        specified = None
+
+    for i in range(n):
+        Bi = I.orientnew('B{}'.format(i), 'Axis', [q[i + 1], I.z])
+        Bi.set_ang_vel(I, u[i + 1] * I.z)
+        frames.append(Bi)
+
+        Pi = points[-1].locatenew('P{}'.format(i + 1), l[i] * Bi.y)
+        Pi.v2pt_theory(points[-1], I, Bi)
+        points.append(Pi)
+
+        Pai = me.Particle('Pa' + str(i + 1), Pi, m[i + 1])
+        particles.append(Pai)
+
+        forces.append((Pi, -m[i + 1] * g * I.y))
+
+        if joint_torques is True:
+
+            specified.append(T[i])
+
+            if i == 0:
+                forces.append((I, -T[i] * I.z))
+
+            if i == n - 1:
+                forces.append((Bi, T[i] * I.z))
+            else:
+                forces.append((Bi, T[i] * I.z - T[i + 1] * I.z))
+
+        kindiffs.append(q[i + 1].diff(t) - u[i + 1])
+
+    if cart_force is True:
+        F = me.dynamicsymbols('F')
+        forces.append((P0, F * I.x))
+        specified.append(F)
+
+    kane = me.KanesMethod(I, q_ind=q, u_ind=u, kd_eqs=kindiffs)
+    kane.kanes_equations(particles, forces)
+
+    return kane

lib/python3.12/site-packages/sympy/physics/mechanics/particle.py

@@ -0,0 +1,209 @@
+from sympy import S
+from sympy.physics.vector import cross, dot
+from sympy.physics.mechanics.body_base import BodyBase
+from sympy.physics.mechanics.inertia import inertia_of_point_mass
+from sympy.utilities.exceptions import sympy_deprecation_warning
+
+__all__ = ['Particle']
+
+
+class Particle(BodyBase):
+    """A particle.
+
+    Explanation
+    ===========
+
+    Particles have a non-zero mass and lack spatial extension; they take up no
+    space.
+
+    Values need to be supplied on initialization, but can be changed later.
+
+    Parameters
+    ==========
+
+    name : str
+        Name of particle
+    point : Point
+        A physics/mechanics Point which represents the position, velocity, and
+        acceleration of this Particle
+    mass : Sympifyable
+        A SymPy expression representing the Particle's mass
+    potential_energy : Sympifyable
+        The potential energy of the Particle.
+
+    Examples
+    ========
+
+    >>> from sympy.physics.mechanics import Particle, Point
+    >>> from sympy import Symbol
+    >>> po = Point('po')
+    >>> m = Symbol('m')
+    >>> pa = Particle('pa', po, m)
+    >>> # Or you could change these later
+    >>> pa.mass = m
+    >>> pa.point = po
+
+    """
+    point = BodyBase.masscenter
+
+    def __init__(self, name, point=None, mass=None):
+        super().__init__(name, point, mass)
+
+    def linear_momentum(self, frame):
+        """Linear momentum of the particle.
+
+        Explanation
+        ===========
+
+        The linear momentum L, of a particle P, with respect to frame N is
+        given by:
+
+        L = m * v
+
+        where m is the mass of the particle, and v is the velocity of the
+        particle in the frame N.
+
+        Parameters
+        ==========
+
+        frame : ReferenceFrame
+            The frame in which linear momentum is desired.
+
+        Examples
+        ========
+
+        >>> from sympy.physics.mechanics import Particle, Point, ReferenceFrame
+        >>> from sympy.physics.mechanics import dynamicsymbols
+        >>> from sympy.physics.vector import init_vprinting
+        >>> init_vprinting(pretty_print=False)
+        >>> m, v = dynamicsymbols('m v')
+        >>> N = ReferenceFrame('N')
+        >>> P = Point('P')
+        >>> A = Particle('A', P, m)
+        >>> P.set_vel(N, v * N.x)
+        >>> A.linear_momentum(N)
+        m*v*N.x
+
+        """
+
+        return self.mass * self.point.vel(frame)
+
+    def angular_momentum(self, point, frame):
+        """Angular momentum of the particle about the point.
+
+        Explanation
+        ===========
+
+        The angular momentum H, about some point O of a particle, P, is given
+        by:
+
+        ``H = cross(r, m * v)``
+
+        where r is the position vector from point O to the particle P, m is
+        the mass of the particle, and v is the velocity of the particle in
+        the inertial frame, N.
+
+        Parameters
+        ==========
+
+        point : Point
+            The point about which angular momentum of the particle is desired.
+
+        frame : ReferenceFrame
+            The frame in which angular momentum is desired.
+
+        Examples
+        ========
+
+        >>> from sympy.physics.mechanics import Particle, Point, ReferenceFrame
+        >>> from sympy.physics.mechanics import dynamicsymbols
+        >>> from sympy.physics.vector import init_vprinting
+        >>> init_vprinting(pretty_print=False)
+        >>> m, v, r = dynamicsymbols('m v r')
+        >>> N = ReferenceFrame('N')
+        >>> O = Point('O')
+        >>> A = O.locatenew('A', r * N.x)
+        >>> P = Particle('P', A, m)
+        >>> P.point.set_vel(N, v * N.y)
+        >>> P.angular_momentum(O, N)
+        m*r*v*N.z
+
+        """
+
+        return cross(self.point.pos_from(point),
+                     self.mass * self.point.vel(frame))
+
+    def kinetic_energy(self, frame):
+        """Kinetic energy of the particle.
+
+        Explanation
+        ===========
+
+        The kinetic energy, T, of a particle, P, is given by:
+
+        ``T = 1/2 (dot(m * v, v))``
+
+        where m is the mass of particle P, and v is the velocity of the
+        particle in the supplied ReferenceFrame.
+
+        Parameters
+        ==========
+
+        frame : ReferenceFrame
+            The Particle's velocity is typically defined with respect to
+            an inertial frame but any relevant frame in which the velocity is
+            known can be supplied.
+
+        Examples
+        ========
+
+        >>> from sympy.physics.mechanics import Particle, Point, ReferenceFrame
+        >>> from sympy import symbols
+        >>> m, v, r = symbols('m v r')
+        >>> N = ReferenceFrame('N')
+        >>> O = Point('O')
+        >>> P = Particle('P', O, m)
+        >>> P.point.set_vel(N, v * N.y)
+        >>> P.kinetic_energy(N)
+        m*v**2/2
+
+        """
+
+        return S.Half * self.mass * dot(self.point.vel(frame),
+                                        self.point.vel(frame))
+
+    def set_potential_energy(self, scalar):
+        sympy_deprecation_warning(
+            """
+The sympy.physics.mechanics.Particle.set_potential_energy()
+method is deprecated. Instead use
+
+    P.potential_energy = scalar
+            """,
+        deprecated_since_version="1.5",
+        active_deprecations_target="deprecated-set-potential-energy",
+        )
+        self.potential_energy = scalar
+
+    def parallel_axis(self, point, frame):
+        """Returns an inertia dyadic of the particle with respect to another
+        point and frame.
+
+        Parameters
+        ==========
+
+        point : sympy.physics.vector.Point
+            The point to express the inertia dyadic about.
+        frame : sympy.physics.vector.ReferenceFrame
+            The reference frame used to construct the dyadic.
+
+        Returns
+        =======
+
+        inertia : sympy.physics.vector.Dyadic
+            The inertia dyadic of the particle expressed about the provided
+            point and frame.
+
+        """
+        return inertia_of_point_mass(self.mass, self.point.pos_from(point),
+                                     frame)

lib/python3.12/site-packages/sympy/physics/mechanics/rigidbody.py

@@ -0,0 +1,314 @@
+from sympy import Symbol, S
+from sympy.physics.vector import ReferenceFrame, Dyadic, Point, dot
+from sympy.physics.mechanics.body_base import BodyBase
+from sympy.physics.mechanics.inertia import inertia_of_point_mass, Inertia
+from sympy.utilities.exceptions import sympy_deprecation_warning
+
+__all__ = ['RigidBody']
+
+
+class RigidBody(BodyBase):
+    """An idealized rigid body.
+
+    Explanation
+    ===========
+
+    This is essentially a container which holds the various components which
+    describe a rigid body: a name, mass, center of mass, reference frame, and
+    inertia.
+
+    All of these need to be supplied on creation, but can be changed
+    afterwards.
+
+    Attributes
+    ==========
+
+    name : string
+        The body's name.
+    masscenter : Point
+        The point which represents the center of mass of the rigid body.
+    frame : ReferenceFrame
+        The ReferenceFrame which the rigid body is fixed in.
+    mass : Sympifyable
+        The body's mass.
+    inertia : (Dyadic, Point)
+        The body's inertia about a point; stored in a tuple as shown above.
+    potential_energy : Sympifyable
+        The potential energy of the RigidBody.
+
+    Examples
+    ========
+
+    >>> from sympy import Symbol
+    >>> from sympy.physics.mechanics import ReferenceFrame, Point, RigidBody
+    >>> from sympy.physics.mechanics import outer
+    >>> m = Symbol('m')
+    >>> A = ReferenceFrame('A')
+    >>> P = Point('P')
+    >>> I = outer (A.x, A.x)
+    >>> inertia_tuple = (I, P)
+    >>> B = RigidBody('B', P, A, m, inertia_tuple)
+    >>> # Or you could change them afterwards
+    >>> m2 = Symbol('m2')
+    >>> B.mass = m2
+
+    """
+
+    def __init__(self, name, masscenter=None, frame=None, mass=None,
+                 inertia=None):
+        super().__init__(name, masscenter, mass)
+        if frame is None:
+            frame = ReferenceFrame(f'{name}_frame')
+        self.frame = frame
+        if inertia is None:
+            ixx = Symbol(f'{name}_ixx')
+            iyy = Symbol(f'{name}_iyy')
+            izz = Symbol(f'{name}_izz')
+            izx = Symbol(f'{name}_izx')
+            ixy = Symbol(f'{name}_ixy')
+            iyz = Symbol(f'{name}_iyz')
+            inertia = Inertia.from_inertia_scalars(self.masscenter, self.frame,
+                                                   ixx, iyy, izz, ixy, iyz, izx)
+        self.inertia = inertia
+
+    def __repr__(self):
+        return (f'{self.__class__.__name__}({repr(self.name)}, masscenter='
+                f'{repr(self.masscenter)}, frame={repr(self.frame)}, mass='
+                f'{repr(self.mass)}, inertia={repr(self.inertia)})')
+
+    @property
+    def frame(self):
+        """The ReferenceFrame fixed to the body."""
+        return self._frame
+
+    @frame.setter
+    def frame(self, F):
+        if not isinstance(F, ReferenceFrame):
+            raise TypeError("RigidBody frame must be a ReferenceFrame object.")
+        self._frame = F
+
+    @property
+    def x(self):
+        """The basis Vector for the body, in the x direction. """
+        return self.frame.x
+
+    @property
+    def y(self):
+        """The basis Vector for the body, in the y direction. """
+        return self.frame.y
+
+    @property
+    def z(self):
+        """The basis Vector for the body, in the z direction. """
+        return self.frame.z
+
+    @property
+    def inertia(self):
+        """The body's inertia about a point; stored as (Dyadic, Point)."""
+        return self._inertia
+
+    @inertia.setter
+    def inertia(self, I):
+        # check if I is of the form (Dyadic, Point)
+        if len(I) != 2 or not isinstance(I[0], Dyadic) or not isinstance(I[1], Point):
+            raise TypeError("RigidBody inertia must be a tuple of the form (Dyadic, Point).")
+
+        self._inertia = Inertia(I[0], I[1])
+        # have I S/O, want I S/S*
+        # I S/O = I S/S* + I S*/O; I S/S* = I S/O - I S*/O
+        # I_S/S* = I_S/O - I_S*/O
+        I_Ss_O = inertia_of_point_mass(self.mass,
+                                       self.masscenter.pos_from(I[1]),
+                                       self.frame)
+        self._central_inertia = I[0] - I_Ss_O
+
+    @property
+    def central_inertia(self):
+        """The body's central inertia dyadic."""
+        return self._central_inertia
+
+    @central_inertia.setter
+    def central_inertia(self, I):
+        if not isinstance(I, Dyadic):
+            raise TypeError("RigidBody inertia must be a Dyadic object.")
+        self.inertia = Inertia(I, self.masscenter)
+
+    def linear_momentum(self, frame):
+        """ Linear momentum of the rigid body.
+
+        Explanation
+        ===========
+
+        The linear momentum L, of a rigid body B, with respect to frame N is
+        given by:
+
+        ``L = m * v``
+
+        where m is the mass of the rigid body, and v is the velocity of the mass
+        center of B in the frame N.
+
+        Parameters
+        ==========
+
+        frame : ReferenceFrame
+            The frame in which linear momentum is desired.
+
+        Examples
+        ========
+
+        >>> from sympy.physics.mechanics import Point, ReferenceFrame, outer
+        >>> from sympy.physics.mechanics import RigidBody, dynamicsymbols
+        >>> from sympy.physics.vector import init_vprinting
+        >>> init_vprinting(pretty_print=False)
+        >>> m, v = dynamicsymbols('m v')
+        >>> N = ReferenceFrame('N')
+        >>> P = Point('P')
+        >>> P.set_vel(N, v * N.x)
+        >>> I = outer (N.x, N.x)
+        >>> Inertia_tuple = (I, P)
+        >>> B = RigidBody('B', P, N, m, Inertia_tuple)
+        >>> B.linear_momentum(N)
+        m*v*N.x
+
+        """
+
+        return self.mass * self.masscenter.vel(frame)
+
+    def angular_momentum(self, point, frame):
+        """Returns the angular momentum of the rigid body about a point in the
+        given frame.
+
+        Explanation
+        ===========
+
+        The angular momentum H of a rigid body B about some point O in a frame N
+        is given by:
+
+        ``H = dot(I, w) + cross(r, m * v)``
+
+        where I and m are the central inertia dyadic and mass of rigid body B, w
+        is the angular velocity of body B in the frame N, r is the position
+        vector from point O to the mass center of B, and v is the velocity of
+        the mass center in the frame N.
+
+        Parameters
+        ==========
+
+        point : Point
+            The point about which angular momentum is desired.
+        frame : ReferenceFrame
+            The frame in which angular momentum is desired.
+
+        Examples
+        ========
+
+        >>> from sympy.physics.mechanics import Point, ReferenceFrame, outer
+        >>> from sympy.physics.mechanics import RigidBody, dynamicsymbols
+        >>> from sympy.physics.vector import init_vprinting
+        >>> init_vprinting(pretty_print=False)
+        >>> m, v, r, omega = dynamicsymbols('m v r omega')
+        >>> N = ReferenceFrame('N')
+        >>> b = ReferenceFrame('b')
+        >>> b.set_ang_vel(N, omega * b.x)
+        >>> P = Point('P')
+        >>> P.set_vel(N, 1 * N.x)
+        >>> I = outer(b.x, b.x)
+        >>> B = RigidBody('B', P, b, m, (I, P))
+        >>> B.angular_momentum(P, N)
+        omega*b.x
+
+        """
+        I = self.central_inertia
+        w = self.frame.ang_vel_in(frame)
+        m = self.mass
+        r = self.masscenter.pos_from(point)
+        v = self.masscenter.vel(frame)
+
+        return I.dot(w) + r.cross(m * v)
+
+    def kinetic_energy(self, frame):
+        """Kinetic energy of the rigid body.
+
+        Explanation
+        ===========
+
+        The kinetic energy, T, of a rigid body, B, is given by:
+
+        ``T = 1/2 * (dot(dot(I, w), w) + dot(m * v, v))``
+
+        where I and m are the central inertia dyadic and mass of rigid body B
+        respectively, w is the body's angular velocity, and v is the velocity of
+        the body's mass center in the supplied ReferenceFrame.
+
+        Parameters
+        ==========
+
+        frame : ReferenceFrame
+            The RigidBody's angular velocity and the velocity of it's mass
+            center are typically defined with respect to an inertial frame but
+            any relevant frame in which the velocities are known can be
+            supplied.
+
+        Examples
+        ========
+
+        >>> from sympy.physics.mechanics import Point, ReferenceFrame, outer
+        >>> from sympy.physics.mechanics import RigidBody
+        >>> from sympy import symbols
+        >>> m, v, r, omega = symbols('m v r omega')
+        >>> N = ReferenceFrame('N')
+        >>> b = ReferenceFrame('b')
+        >>> b.set_ang_vel(N, omega * b.x)
+        >>> P = Point('P')
+        >>> P.set_vel(N, v * N.x)
+        >>> I = outer (b.x, b.x)
+        >>> inertia_tuple = (I, P)
+        >>> B = RigidBody('B', P, b, m, inertia_tuple)
+        >>> B.kinetic_energy(N)
+        m*v**2/2 + omega**2/2
+
+        """
+
+        rotational_KE = S.Half * dot(
+            self.frame.ang_vel_in(frame),
+            dot(self.central_inertia, self.frame.ang_vel_in(frame)))
+        translational_KE = S.Half * self.mass * dot(self.masscenter.vel(frame),
+                                                    self.masscenter.vel(frame))
+        return rotational_KE + translational_KE
+
+    def set_potential_energy(self, scalar):
+        sympy_deprecation_warning(
+            """
+The sympy.physics.mechanics.RigidBody.set_potential_energy()
+method is deprecated. Instead use
+
+    B.potential_energy = scalar
+            """,
+        deprecated_since_version="1.5",
+        active_deprecations_target="deprecated-set-potential-energy",
+        )
+        self.potential_energy = scalar
+
+    def parallel_axis(self, point, frame=None):
+        """Returns the inertia dyadic of the body with respect to another point.
+
+        Parameters
+        ==========
+
+        point : sympy.physics.vector.Point
+            The point to express the inertia dyadic about.
+        frame : sympy.physics.vector.ReferenceFrame
+            The reference frame used to construct the dyadic.
+
+        Returns
+        =======
+
+        inertia : sympy.physics.vector.Dyadic
+            The inertia dyadic of the rigid body expressed about the provided
+            point.
+
+        """
+        if frame is None:
+            frame = self.frame
+        return self.central_inertia + inertia_of_point_mass(
+            self.mass, self.masscenter.pos_from(point), frame)

lib/python3.12/site-packages/sympy/physics/mechanics/system.py

@@ -0,0 +1,1553 @@
+from functools import wraps
+
+from sympy.core.basic import Basic
+from sympy.matrices.immutable import ImmutableMatrix
+from sympy.matrices.dense import Matrix, eye, zeros
+from sympy.core.containers import OrderedSet
+from sympy.physics.mechanics.actuator import ActuatorBase
+from sympy.physics.mechanics.body_base import BodyBase
+from sympy.physics.mechanics.functions import (
+    Lagrangian, _validate_coordinates, find_dynamicsymbols)
+from sympy.physics.mechanics.joint import Joint
+from sympy.physics.mechanics.kane import KanesMethod
+from sympy.physics.mechanics.lagrange import LagrangesMethod
+from sympy.physics.mechanics.loads import _parse_load, gravity
+from sympy.physics.mechanics.method import _Methods
+from sympy.physics.mechanics.particle import Particle
+from sympy.physics.vector import Point, ReferenceFrame, dynamicsymbols
+from sympy.utilities.iterables import iterable
+from sympy.utilities.misc import filldedent
+
+__all__ = ['SymbolicSystem', 'System']
+
+
+def _reset_eom_method(method):
+    """Decorator to reset the eom_method if a property is changed."""
+
+    @wraps(method)
+    def wrapper(self, *args, **kwargs):
+        self._eom_method = None
+        return method(self, *args, **kwargs)
+
+    return wrapper
+
+
+class System(_Methods):
+    """Class to define a multibody system and form its equations of motion.
+
+    Explanation
+    ===========
+
+    A ``System`` instance stores the different objects associated with a model,
+    including bodies, joints, constraints, and other relevant information. With
+    all the relationships between components defined, the ``System`` can be used
+    to form the equations of motion using a backend, such as ``KanesMethod``.
+    The ``System`` has been designed to be compatible with third-party
+    libraries for greater flexibility and integration with other tools.
+
+    Attributes
+    ==========
+
+    frame : ReferenceFrame
+        Inertial reference frame of the system.
+    fixed_point : Point
+        A fixed point in the inertial reference frame.
+    x : Vector
+        Unit vector fixed in the inertial reference frame.
+    y : Vector
+        Unit vector fixed in the inertial reference frame.
+    z : Vector
+        Unit vector fixed in the inertial reference frame.
+    q : ImmutableMatrix
+        Matrix of all the generalized coordinates, i.e. the independent
+        generalized coordinates stacked upon the dependent.
+    u : ImmutableMatrix
+        Matrix of all the generalized speeds, i.e. the independent generealized
+        speeds stacked upon the dependent.
+    q_ind : ImmutableMatrix
+        Matrix of the independent generalized coordinates.
+    q_dep : ImmutableMatrix
+        Matrix of the dependent generalized coordinates.
+    u_ind : ImmutableMatrix
+        Matrix of the independent generalized speeds.
+    u_dep : ImmutableMatrix
+        Matrix of the dependent generalized speeds.
+    u_aux : ImmutableMatrix
+        Matrix of auxiliary generalized speeds.
+    kdes : ImmutableMatrix
+        Matrix of the kinematical differential equations as expressions equated
+        to the zero matrix.
+    bodies : tuple of BodyBase subclasses
+        Tuple of all bodies that make up the system.
+    joints : tuple of Joint
+        Tuple of all joints that connect bodies in the system.
+    loads : tuple of LoadBase subclasses
+        Tuple of all loads that have been applied to the system.
+    actuators : tuple of ActuatorBase subclasses
+        Tuple of all actuators present in the system.
+    holonomic_constraints : ImmutableMatrix
+        Matrix with the holonomic constraints as expressions equated to the zero
+        matrix.
+    nonholonomic_constraints : ImmutableMatrix
+        Matrix with the nonholonomic constraints as expressions equated to the
+        zero matrix.
+    velocity_constraints : ImmutableMatrix
+        Matrix with the velocity constraints as expressions equated to the zero
+        matrix. These are by default derived as the time derivatives of the
+        holonomic constraints extended with the nonholonomic constraints.
+    eom_method : subclass of KanesMethod or LagrangesMethod
+        Backend for forming the equations of motion.
+
+    Examples
+    ========
+
+    In the example below a cart with a pendulum is created. The cart moves along
+    the x axis of the rail and the pendulum rotates about the z axis. The length
+    of the pendulum is ``l`` with the pendulum represented as a particle. To
+    move the cart a time dependent force ``F`` is applied to the cart.
+
+    We first need to import some functions and create some of our variables.
+
+    >>> from sympy import symbols, simplify
+    >>> from sympy.physics.mechanics import (
+    ...     mechanics_printing, dynamicsymbols, RigidBody, Particle,
+    ...     ReferenceFrame, PrismaticJoint, PinJoint, System)
+    >>> mechanics_printing(pretty_print=False)
+    >>> g, l = symbols('g l')
+    >>> F = dynamicsymbols('F')
+
+    The next step is to create bodies. It is also useful to create a frame for
+    locating the particle with respect to the pin joint later on, as a particle
+    does not have a body-fixed frame.
+
+    >>> rail = RigidBody('rail')
+    >>> cart = RigidBody('cart')
+    >>> bob = Particle('bob')
+    >>> bob_frame = ReferenceFrame('bob_frame')
+
+    Initialize the system, with the rail as the Newtonian reference. The body is
+    also automatically added to the system.
+
+    >>> system = System.from_newtonian(rail)
+    >>> print(system.bodies[0])
+    rail
+
+    Create the joints, while immediately also adding them to the system.
+
+    >>> system.add_joints(
+    ...     PrismaticJoint('slider', rail, cart, joint_axis=rail.x),
+    ...     PinJoint('pin', cart, bob, joint_axis=cart.z,
+    ...              child_interframe=bob_frame,
+    ...              child_point=l * bob_frame.y)
+    ... )
+    >>> system.joints
+    (PrismaticJoint: slider  parent: rail  child: cart,
+    PinJoint: pin  parent: cart  child: bob)
+
+    While adding the joints, the associated generalized coordinates, generalized
+    speeds, kinematic differential equations and bodies are also added to the
+    system.
+
+    >>> system.q
+    Matrix([
+    [q_slider],
+    [   q_pin]])
+    >>> system.u
+    Matrix([
+    [u_slider],
+    [   u_pin]])
+    >>> system.kdes
+    Matrix([
+    [u_slider - q_slider'],
+    [      u_pin - q_pin']])
+    >>> [body.name for body in system.bodies]
+    ['rail', 'cart', 'bob']
+
+    With the kinematics established, we can now apply gravity and the cart force
+    ``F``.
+
+    >>> system.apply_uniform_gravity(-g * system.y)
+    >>> system.add_loads((cart.masscenter, F * rail.x))
+    >>> system.loads
+    ((rail_masscenter, - g*rail_mass*rail_frame.y),
+     (cart_masscenter, - cart_mass*g*rail_frame.y),
+     (bob_masscenter, - bob_mass*g*rail_frame.y),
+     (cart_masscenter, F*rail_frame.x))
+
+    With the entire system defined, we can now form the equations of motion.
+    Before forming the equations of motion, one can also run some checks that
+    will try to identify some common errors.
+
+    >>> system.validate_system()
+    >>> system.form_eoms()
+    Matrix([
+    [bob_mass*l*u_pin**2*sin(q_pin) - bob_mass*l*cos(q_pin)*u_pin'
+     - (bob_mass + cart_mass)*u_slider' + F],
+    [                   -bob_mass*g*l*sin(q_pin) - bob_mass*l**2*u_pin'
+     - bob_mass*l*cos(q_pin)*u_slider']])
+    >>> simplify(system.mass_matrix)
+    Matrix([
+    [ bob_mass + cart_mass, bob_mass*l*cos(q_pin)],
+    [bob_mass*l*cos(q_pin),         bob_mass*l**2]])
+    >>> system.forcing
+    Matrix([
+    [bob_mass*l*u_pin**2*sin(q_pin) + F],
+    [          -bob_mass*g*l*sin(q_pin)]])
+
+    The complexity of the above example can be increased if we add a constraint
+    to prevent the particle from moving in the horizontal (x) direction. This
+    can be done by adding a holonomic constraint. After which we should also
+    redefine what our (in)dependent generalized coordinates and speeds are.
+
+    >>> system.add_holonomic_constraints(
+    ...     bob.masscenter.pos_from(rail.masscenter).dot(system.x)
+    ... )
+    >>> system.q_ind = system.get_joint('pin').coordinates
+    >>> system.q_dep = system.get_joint('slider').coordinates
+    >>> system.u_ind = system.get_joint('pin').speeds
+    >>> system.u_dep = system.get_joint('slider').speeds
+
+    With the updated system the equations of motion can be formed again.
+
+    >>> system.validate_system()
+    >>> system.form_eoms()
+    Matrix([[-bob_mass*g*l*sin(q_pin)
+             - bob_mass*l**2*u_pin'
+             - bob_mass*l*cos(q_pin)*u_slider'
+             - l*(bob_mass*l*u_pin**2*sin(q_pin)
+             - bob_mass*l*cos(q_pin)*u_pin'
+             - (bob_mass + cart_mass)*u_slider')*cos(q_pin)
+             - l*F*cos(q_pin)]])
+    >>> simplify(system.mass_matrix)
+    Matrix([
+    [bob_mass*l**2*sin(q_pin)**2, -cart_mass*l*cos(q_pin)],
+    [               l*cos(q_pin),                       1]])
+    >>> simplify(system.forcing)
+    Matrix([
+    [-l*(bob_mass*g*sin(q_pin) + bob_mass*l*u_pin**2*sin(2*q_pin)/2
+     + F*cos(q_pin))],
+    [
+    l*u_pin**2*sin(q_pin)]])
+
+    """
+
+    def __init__(self, frame=None, fixed_point=None):
+        """Initialize the system.
+
+        Parameters
+        ==========
+
+        frame : ReferenceFrame, optional
+            The inertial frame of the system. If none is supplied, a new frame
+            will be created.
+        fixed_point : Point, optional
+            A fixed point in the inertial reference frame. If none is supplied,
+            a new fixed_point will be created.
+
+        """
+        if frame is None:
+            frame = ReferenceFrame('inertial_frame')
+        elif not isinstance(frame, ReferenceFrame):
+            raise TypeError('Frame must be an instance of ReferenceFrame.')
+        self._frame = frame
+        if fixed_point is None:
+            fixed_point = Point('inertial_point')
+        elif not isinstance(fixed_point, Point):
+            raise TypeError('Fixed point must be an instance of Point.')
+        self._fixed_point = fixed_point
+        self._fixed_point.set_vel(self._frame, 0)
+        self._q_ind = ImmutableMatrix(1, 0, []).T
+        self._q_dep = ImmutableMatrix(1, 0, []).T
+        self._u_ind = ImmutableMatrix(1, 0, []).T
+        self._u_dep = ImmutableMatrix(1, 0, []).T
+        self._u_aux = ImmutableMatrix(1, 0, []).T
+        self._kdes = ImmutableMatrix(1, 0, []).T
+        self._hol_coneqs = ImmutableMatrix(1, 0, []).T
+        self._nonhol_coneqs = ImmutableMatrix(1, 0, []).T
+        self._vel_constrs = None
+        self._bodies = []
+        self._joints = []
+        self._loads = []
+        self._actuators = []
+        self._eom_method = None
+
+    @classmethod
+    def from_newtonian(cls, newtonian):
+        """Constructs the system with respect to a Newtonian body."""
+        if isinstance(newtonian, Particle):
+            raise TypeError('A Particle has no frame so cannot act as '
+                            'the Newtonian.')
+        system = cls(frame=newtonian.frame, fixed_point=newtonian.masscenter)
+        system.add_bodies(newtonian)
+        return system
+
+    @property
+    def fixed_point(self):
+        """Fixed point in the inertial reference frame."""
+        return self._fixed_point
+
+    @property
+    def frame(self):
+        """Inertial reference frame of the system."""
+        return self._frame
+
+    @property
+    def x(self):
+        """Unit vector fixed in the inertial reference frame."""
+        return self._frame.x
+
+    @property
+    def y(self):
+        """Unit vector fixed in the inertial reference frame."""
+        return self._frame.y
+
+    @property
+    def z(self):
+        """Unit vector fixed in the inertial reference frame."""
+        return self._frame.z
+
+    @property
+    def bodies(self):
+        """Tuple of all bodies that have been added to the system."""
+        return tuple(self._bodies)
+
+    @bodies.setter
+    @_reset_eom_method
+    def bodies(self, bodies):
+        bodies = self._objects_to_list(bodies)
+        self._check_objects(bodies, [], BodyBase, 'Bodies', 'bodies')
+        self._bodies = bodies
+
+    @property
+    def joints(self):
+        """Tuple of all joints that have been added to the system."""
+        return tuple(self._joints)
+
+    @joints.setter
+    @_reset_eom_method
+    def joints(self, joints):
+        joints = self._objects_to_list(joints)
+        self._check_objects(joints, [], Joint, 'Joints', 'joints')
+        self._joints = []
+        self.add_joints(*joints)
+
+    @property
+    def loads(self):
+        """Tuple of loads that have been applied on the system."""
+        return tuple(self._loads)
+
+    @loads.setter
+    @_reset_eom_method
+    def loads(self, loads):
+        loads = self._objects_to_list(loads)
+        self._loads = [_parse_load(load) for load in loads]
+
+    @property
+    def actuators(self):
+        """Tuple of actuators present in the system."""
+        return tuple(self._actuators)
+
+    @actuators.setter
+    @_reset_eom_method
+    def actuators(self, actuators):
+        actuators = self._objects_to_list(actuators)
+        self._check_objects(actuators, [], ActuatorBase, 'Actuators',
+                            'actuators')
+        self._actuators = actuators
+
+    @property
+    def q(self):
+        """Matrix of all the generalized coordinates with the independent
+        stacked upon the dependent."""
+        return self._q_ind.col_join(self._q_dep)
+
+    @property
+    def u(self):
+        """Matrix of all the generalized speeds with the independent stacked
+        upon the dependent."""
+        return self._u_ind.col_join(self._u_dep)
+
+    @property
+    def q_ind(self):
+        """Matrix of the independent generalized coordinates."""
+        return self._q_ind
+
+    @q_ind.setter
+    @_reset_eom_method
+    def q_ind(self, q_ind):
+        self._q_ind, self._q_dep = self._parse_coordinates(
+            self._objects_to_list(q_ind), True, [], self.q_dep, 'coordinates')
+
+    @property
+    def q_dep(self):
+        """Matrix of the dependent generalized coordinates."""
+        return self._q_dep
+
+    @q_dep.setter
+    @_reset_eom_method
+    def q_dep(self, q_dep):
+        self._q_ind, self._q_dep = self._parse_coordinates(
+            self._objects_to_list(q_dep), False, self.q_ind, [], 'coordinates')
+
+    @property
+    def u_ind(self):
+        """Matrix of the independent generalized speeds."""
+        return self._u_ind
+
+    @u_ind.setter
+    @_reset_eom_method
+    def u_ind(self, u_ind):
+        self._u_ind, self._u_dep = self._parse_coordinates(
+            self._objects_to_list(u_ind), True, [], self.u_dep, 'speeds')
+
+    @property
+    def u_dep(self):
+        """Matrix of the dependent generalized speeds."""
+        return self._u_dep
+
+    @u_dep.setter
+    @_reset_eom_method
+    def u_dep(self, u_dep):
+        self._u_ind, self._u_dep = self._parse_coordinates(
+            self._objects_to_list(u_dep), False, self.u_ind, [], 'speeds')
+
+    @property
+    def u_aux(self):
+        """Matrix of auxiliary generalized speeds."""
+        return self._u_aux
+
+    @u_aux.setter
+    @_reset_eom_method
+    def u_aux(self, u_aux):
+        self._u_aux = self._parse_coordinates(
+            self._objects_to_list(u_aux), True, [], [], 'u_auxiliary')[0]
+
+    @property
+    def kdes(self):
+        """Kinematical differential equations as expressions equated to the zero
+        matrix. These equations describe the coupling between the generalized
+        coordinates and the generalized speeds."""
+        return self._kdes
+
+    @kdes.setter
+    @_reset_eom_method
+    def kdes(self, kdes):
+        kdes = self._objects_to_list(kdes)
+        self._kdes = self._parse_expressions(
+            kdes, [], 'kinematic differential equations')
+
+    @property
+    def holonomic_constraints(self):
+        """Matrix with the holonomic constraints as expressions equated to the
+        zero matrix."""
+        return self._hol_coneqs
+
+    @holonomic_constraints.setter
+    @_reset_eom_method
+    def holonomic_constraints(self, constraints):
+        constraints = self._objects_to_list(constraints)
+        self._hol_coneqs = self._parse_expressions(
+            constraints, [], 'holonomic constraints')
+
+    @property
+    def nonholonomic_constraints(self):
+        """Matrix with the nonholonomic constraints as expressions equated to
+        the zero matrix."""
+        return self._nonhol_coneqs
+
+    @nonholonomic_constraints.setter
+    @_reset_eom_method
+    def nonholonomic_constraints(self, constraints):
+        constraints = self._objects_to_list(constraints)
+        self._nonhol_coneqs = self._parse_expressions(
+            constraints, [], 'nonholonomic constraints')
+
+    @property
+    def velocity_constraints(self):
+        """Matrix with the velocity constraints as expressions equated to the
+        zero matrix. The velocity constraints are by default derived from the
+        holonomic and nonholonomic constraints unless they are explicitly set.
+        """
+        if self._vel_constrs is None:
+            return self.holonomic_constraints.diff(dynamicsymbols._t).col_join(
+                self.nonholonomic_constraints)
+        return self._vel_constrs
+
+    @velocity_constraints.setter
+    @_reset_eom_method
+    def velocity_constraints(self, constraints):
+        if constraints is None:
+            self._vel_constrs = None
+            return
+        constraints = self._objects_to_list(constraints)
+        self._vel_constrs = self._parse_expressions(
+            constraints, [], 'velocity constraints')
+
+    @property
+    def eom_method(self):
+        """Backend for forming the equations of motion."""
+        return self._eom_method
+
+    @staticmethod
+    def _objects_to_list(lst):
+        """Helper to convert passed objects to a list."""
+        if not iterable(lst):  # Only one object
+            return [lst]
+        return list(lst[:])  # converts Matrix and tuple to flattened list
+
+    @staticmethod
+    def _check_objects(objects, obj_lst, expected_type, obj_name, type_name):
+        """Helper to check the objects that are being added to the system.
+
+        Explanation
+        ===========
+        This method checks that the objects that are being added to the system
+        are of the correct type and have not already been added. If any of the
+        objects are not of the correct type or have already been added, then
+        an error is raised.
+
+        Parameters
+        ==========
+        objects : iterable
+            The objects that would be added to the system.
+        obj_lst : list
+            The list of objects that are already in the system.
+        expected_type : type
+            The type that the objects should be.
+        obj_name : str
+            The name of the category of objects. This string is used to
+            formulate the error message for the user.
+        type_name : str
+            The name of the type that the objects should be. This string is used
+            to formulate the error message for the user.
+
+        """
+        seen = set(obj_lst)
+        duplicates = set()
+        wrong_types = set()
+        for obj in objects:
+            if not isinstance(obj, expected_type):
+                wrong_types.add(obj)
+            if obj in seen:
+                duplicates.add(obj)
+            else:
+                seen.add(obj)
+        if wrong_types:
+            raise TypeError(f'{obj_name} {wrong_types} are not {type_name}.')
+        if duplicates:
+            raise ValueError(f'{obj_name} {duplicates} have already been added '
+                             f'to the system.')
+
+    def _parse_coordinates(self, new_coords, independent, old_coords_ind,
+                           old_coords_dep, coord_type='coordinates'):
+        """Helper to parse coordinates and speeds."""
+        # Construct lists of the independent and dependent coordinates
+        coords_ind, coords_dep = old_coords_ind[:], old_coords_dep[:]
+        if not iterable(independent):
+            independent = [independent] * len(new_coords)
+        for coord, indep in zip(new_coords, independent):
+            if indep:
+                coords_ind.append(coord)
+            else:
+                coords_dep.append(coord)
+        # Check types and duplicates
+        current = {'coordinates': self.q_ind[:] + self.q_dep[:],
+                   'speeds': self.u_ind[:] + self.u_dep[:],
+                   'u_auxiliary': self._u_aux[:],
+                   coord_type: coords_ind + coords_dep}
+        _validate_coordinates(**current)
+        return (ImmutableMatrix(1, len(coords_ind), coords_ind).T,
+                ImmutableMatrix(1, len(coords_dep), coords_dep).T)
+
+    @staticmethod
+    def _parse_expressions(new_expressions, old_expressions, name,
+                           check_negatives=False):
+        """Helper to parse expressions like constraints."""
+        old_expressions = old_expressions[:]
+        new_expressions = list(new_expressions)  # Converts a possible tuple
+        if check_negatives:
+            check_exprs = old_expressions + [-expr for expr in old_expressions]
+        else:
+            check_exprs = old_expressions
+        System._check_objects(new_expressions, check_exprs, Basic, name,
+                              'expressions')
+        for expr in new_expressions:
+            if expr == 0:
+                raise ValueError(f'Parsed {name} are zero.')
+        return ImmutableMatrix(1, len(old_expressions) + len(new_expressions),
+                               old_expressions + new_expressions).T
+
+    @_reset_eom_method
+    def add_coordinates(self, *coordinates, independent=True):
+        """Add generalized coordinate(s) to the system.
+
+        Parameters
+        ==========
+
+        *coordinates : dynamicsymbols
+            One or more generalized coordinates to be added to the system.
+        independent : bool or list of bool, optional
+            Boolean whether a coordinate is dependent or independent. The
+            default is True, so the coordinates are added as independent by
+            default.
+
+        """
+        self._q_ind, self._q_dep = self._parse_coordinates(
+            coordinates, independent, self.q_ind, self.q_dep, 'coordinates')
+
+    @_reset_eom_method
+    def add_speeds(self, *speeds, independent=True):
+        """Add generalized speed(s) to the system.
+
+        Parameters
+        ==========
+
+        *speeds : dynamicsymbols
+            One or more generalized speeds to be added to the system.
+        independent : bool or list of bool, optional
+            Boolean whether a speed is dependent or independent. The default is
+            True, so the speeds are added as independent by default.
+
+        """
+        self._u_ind, self._u_dep = self._parse_coordinates(
+            speeds, independent, self.u_ind, self.u_dep, 'speeds')
+
+    @_reset_eom_method
+    def add_auxiliary_speeds(self, *speeds):
+        """Add auxiliary speed(s) to the system.
+
+        Parameters
+        ==========
+
+        *speeds : dynamicsymbols
+            One or more auxiliary speeds to be added to the system.
+
+        """
+        self._u_aux = self._parse_coordinates(
+            speeds, True, self._u_aux, [], 'u_auxiliary')[0]
+
+    @_reset_eom_method
+    def add_kdes(self, *kdes):
+        """Add kinematic differential equation(s) to the system.
+
+        Parameters
+        ==========
+
+        *kdes : Expr
+            One or more kinematic differential equations.
+
+        """
+        self._kdes = self._parse_expressions(
+            kdes, self.kdes, 'kinematic differential equations',
+            check_negatives=True)
+
+    @_reset_eom_method
+    def add_holonomic_constraints(self, *constraints):
+        """Add holonomic constraint(s) to the system.
+
+        Parameters
+        ==========
+
+        *constraints : Expr
+            One or more holonomic constraints, which are expressions that should
+            be zero.
+
+        """
+        self._hol_coneqs = self._parse_expressions(
+            constraints, self._hol_coneqs, 'holonomic constraints',
+            check_negatives=True)
+
+    @_reset_eom_method
+    def add_nonholonomic_constraints(self, *constraints):
+        """Add nonholonomic constraint(s) to the system.
+
+        Parameters
+        ==========
+
+        *constraints : Expr
+            One or more nonholonomic constraints, which are expressions that
+            should be zero.
+
+        """
+        self._nonhol_coneqs = self._parse_expressions(
+            constraints, self._nonhol_coneqs, 'nonholonomic constraints',
+            check_negatives=True)
+
+    @_reset_eom_method
+    def add_bodies(self, *bodies):
+        """Add body(ies) to the system.
+
+        Parameters
+        ==========
+
+        bodies : Particle or RigidBody
+            One or more bodies.
+
+        """
+        self._check_objects(bodies, self.bodies, BodyBase, 'Bodies', 'bodies')
+        self._bodies.extend(bodies)
+
+    @_reset_eom_method
+    def add_loads(self, *loads):
+        """Add load(s) to the system.
+
+        Parameters
+        ==========
+
+        *loads : Force or Torque
+            One or more loads.
+
+        """
+        loads = [_parse_load(load) for load in loads]  # Checks the loads
+        self._loads.extend(loads)
+
+    @_reset_eom_method
+    def apply_uniform_gravity(self, acceleration):
+        """Apply uniform gravity to all bodies in the system by adding loads.
+
+        Parameters
+        ==========
+
+        acceleration : Vector
+            The acceleration due to gravity.
+
+        """
+        self.add_loads(*gravity(acceleration, *self.bodies))
+
+    @_reset_eom_method
+    def add_actuators(self, *actuators):
+        """Add actuator(s) to the system.
+
+        Parameters
+        ==========
+
+        *actuators : subclass of ActuatorBase
+            One or more actuators.
+
+        """
+        self._check_objects(actuators, self.actuators, ActuatorBase,
+                            'Actuators', 'actuators')
+        self._actuators.extend(actuators)
+
+    @_reset_eom_method
+    def add_joints(self, *joints):
+        """Add joint(s) to the system.
+
+        Explanation
+        ===========
+
+        This methods adds one or more joints to the system including its
+        associated objects, i.e. generalized coordinates, generalized speeds,
+        kinematic differential equations and the bodies.
+
+        Parameters
+        ==========
+
+        *joints : subclass of Joint
+            One or more joints.
+
+        Notes
+        =====
+
+        For the generalized coordinates, generalized speeds and bodies it is
+        checked whether they are already known by the system instance. If they
+        are, then they are not added. The kinematic differential equations are
+        however always added to the system, so you should not also manually add
+        those on beforehand.
+
+        """
+        self._check_objects(joints, self.joints, Joint, 'Joints', 'joints')
+        self._joints.extend(joints)
+        coordinates, speeds, kdes, bodies = (OrderedSet() for _ in range(4))
+        for joint in joints:
+            coordinates.update(joint.coordinates)
+            speeds.update(joint.speeds)
+            kdes.update(joint.kdes)
+            bodies.update((joint.parent, joint.child))
+        coordinates = coordinates.difference(self.q)
+        speeds = speeds.difference(self.u)
+        kdes = kdes.difference(self.kdes[:] + (-self.kdes)[:])
+        bodies = bodies.difference(self.bodies)
+        self.add_coordinates(*tuple(coordinates))
+        self.add_speeds(*tuple(speeds))
+        self.add_kdes(*(kde for kde in tuple(kdes) if not kde == 0))
+        self.add_bodies(*tuple(bodies))
+
+    def get_body(self, name):
+        """Retrieve a body from the system by name.
+
+        Parameters
+        ==========
+
+        name : str
+            The name of the body to retrieve.
+
+        Returns
+        =======
+
+        RigidBody or Particle
+            The body with the given name, or None if no such body exists.
+
+        """
+        for body in self._bodies:
+            if body.name == name:
+                return body
+
+    def get_joint(self, name):
+        """Retrieve a joint from the system by name.
+
+        Parameters
+        ==========
+
+        name : str
+            The name of the joint to retrieve.
+
+        Returns
+        =======
+
+        subclass of Joint
+            The joint with the given name, or None if no such joint exists.
+
+        """
+        for joint in self._joints:
+            if joint.name == name:
+                return joint
+
+    def _form_eoms(self):
+        return self.form_eoms()
+
+    def form_eoms(self, eom_method=KanesMethod, **kwargs):
+        """Form the equations of motion of the system.
+
+        Parameters
+        ==========
+
+        eom_method : subclass of KanesMethod or LagrangesMethod
+            Backend class to be used for forming the equations of motion. The
+            default is ``KanesMethod``.
+
+        Returns
+        ========
+
+        ImmutableMatrix
+            Vector of equations of motions.
+
+        Examples
+        ========
+
+        This is a simple example for a one degree of freedom translational
+        spring-mass-damper.
+
+        >>> from sympy import S, symbols
+        >>> from sympy.physics.mechanics import (
+        ...     LagrangesMethod, dynamicsymbols, PrismaticJoint, Particle,
+        ...     RigidBody, System)
+        >>> q = dynamicsymbols('q')
+        >>> qd = dynamicsymbols('q', 1)
+        >>> m, k, b = symbols('m k b')
+        >>> wall = RigidBody('W')
+        >>> system = System.from_newtonian(wall)
+        >>> bob = Particle('P', mass=m)
+        >>> bob.potential_energy = S.Half * k * q**2
+        >>> system.add_joints(PrismaticJoint('J', wall, bob, q, qd))
+        >>> system.add_loads((bob.masscenter, b * qd * system.x))
+        >>> system.form_eoms(LagrangesMethod)
+        Matrix([[-b*Derivative(q(t), t) + k*q(t) + m*Derivative(q(t), (t, 2))]])
+
+        We can also solve for the states using the 'rhs' method.
+
+        >>> system.rhs()
+        Matrix([
+        [               Derivative(q(t), t)],
+        [(b*Derivative(q(t), t) - k*q(t))/m]])
+
+        """
+        # KanesMethod does not accept empty iterables
+        loads = self.loads + tuple(
+            load for act in self.actuators for load in act.to_loads())
+        loads = loads if loads else None
+        if issubclass(eom_method, KanesMethod):
+            disallowed_kwargs = {
+                "frame", "q_ind", "u_ind", "kd_eqs", "q_dependent",
+                "u_dependent", "u_auxiliary", "configuration_constraints",
+                "velocity_constraints", "forcelist", "bodies"}
+            wrong_kwargs = disallowed_kwargs.intersection(kwargs)
+            if wrong_kwargs:
+                raise ValueError(
+                    f"The following keyword arguments are not allowed to be "
+                    f"overwritten in {eom_method.__name__}: {wrong_kwargs}.")
+            kwargs = {"frame": self.frame, "q_ind": self.q_ind,
+                      "u_ind": self.u_ind, "kd_eqs": self.kdes,
+                      "q_dependent": self.q_dep, "u_dependent": self.u_dep,
+                      "configuration_constraints": self.holonomic_constraints,
+                      "velocity_constraints": self.velocity_constraints,
+                      "u_auxiliary": self.u_aux,
+                      "forcelist": loads, "bodies": self.bodies,
+                      "explicit_kinematics": False, **kwargs}
+            self._eom_method = eom_method(**kwargs)
+        elif issubclass(eom_method, LagrangesMethod):
+            disallowed_kwargs = {
+                "frame", "qs", "forcelist", "bodies", "hol_coneqs",
+                "nonhol_coneqs", "Lagrangian"}
+            wrong_kwargs = disallowed_kwargs.intersection(kwargs)
+            if wrong_kwargs:
+                raise ValueError(
+                    f"The following keyword arguments are not allowed to be "
+                    f"overwritten in {eom_method.__name__}: {wrong_kwargs}.")
+            kwargs = {"frame": self.frame, "qs": self.q, "forcelist": loads,
+                      "bodies": self.bodies,
+                      "hol_coneqs": self.holonomic_constraints,
+                      "nonhol_coneqs": self.nonholonomic_constraints, **kwargs}
+            if "Lagrangian" not in kwargs:
+                kwargs["Lagrangian"] = Lagrangian(kwargs["frame"],
+                                                  *kwargs["bodies"])
+            self._eom_method = eom_method(**kwargs)
+        else:
+            raise NotImplementedError(f'{eom_method} has not been implemented.')
+        return self.eom_method._form_eoms()
+
+    def rhs(self, inv_method=None):
+        """Compute the equations of motion in the explicit form.
+
+        Parameters
+        ==========
+
+        inv_method : str
+            The specific sympy inverse matrix calculation method to use. For a
+            list of valid methods, see
+            :meth:`~sympy.matrices.matrixbase.MatrixBase.inv`
+
+        Returns
+        ========
+
+        ImmutableMatrix
+            Equations of motion in the explicit form.
+
+        See Also
+        ========
+
+        sympy.physics.mechanics.kane.KanesMethod.rhs:
+            KanesMethod's ``rhs`` function.
+        sympy.physics.mechanics.lagrange.LagrangesMethod.rhs:
+            LagrangesMethod's ``rhs`` function.
+
+        """
+        return self.eom_method.rhs(inv_method=inv_method)
+
+    @property
+    def mass_matrix(self):
+        r"""The mass matrix of the system.
+
+        Explanation
+        ===========
+
+        The mass matrix $M_d$ and the forcing vector $f_d$ of a system describe
+        the system's dynamics according to the following equations:
+
+        .. math::
+            M_d \dot{u} = f_d
+
+        where $\dot{u}$ is the time derivative of the generalized speeds.
+
+        """
+        return self.eom_method.mass_matrix
+
+    @property
+    def mass_matrix_full(self):
+        r"""The mass matrix of the system, augmented by the kinematic
+        differential equations in explicit or implicit form.
+
+        Explanation
+        ===========
+
+        The full mass matrix $M_m$ and the full forcing vector $f_m$ of a system
+        describe the dynamics and kinematics according to the following
+        equation:
+
+        .. math::
+            M_m \dot{x} = f_m
+
+        where $x$ is the state vector stacking $q$ and $u$.
+
+        """
+        return self.eom_method.mass_matrix_full
+
+    @property
+    def forcing(self):
+        """The forcing vector of the system."""
+        return self.eom_method.forcing
+
+    @property
+    def forcing_full(self):
+        """The forcing vector of the system, augmented by the kinematic
+        differential equations in explicit or implicit form."""
+        return self.eom_method.forcing_full
+
+    def validate_system(self, eom_method=KanesMethod, check_duplicates=False):
+        """Validates the system using some basic checks.
+
+        Explanation
+        ===========
+
+        This method validates the system based on the following checks:
+
+        - The number of dependent generalized coordinates should equal the
+          number of holonomic constraints.
+        - All generalized coordinates defined by the joints should also be known
+          to the system.
+        - If ``KanesMethod`` is used as a ``eom_method``:
+            - All generalized speeds and kinematic differential equations
+              defined by the joints should also be known to the system.
+            - The number of dependent generalized speeds should equal the number
+              of velocity constraints.
+            - The number of generalized coordinates should be less than or equal
+              to the number of generalized speeds.
+            - The number of generalized coordinates should equal the number of
+              kinematic differential equations.
+        - If ``LagrangesMethod`` is used as ``eom_method``:
+            - There should not be any generalized speeds that are not
+              derivatives of the generalized coordinates (this includes the
+              generalized speeds defined by the joints).
+
+        Parameters
+        ==========
+
+        eom_method : subclass of KanesMethod or LagrangesMethod
+            Backend class that will be used for forming the equations of motion.
+            There are different checks for the different backends. The default
+            is ``KanesMethod``.
+        check_duplicates : bool
+            Boolean whether the system should be checked for duplicate
+            definitions. The default is False, because duplicates are already
+            checked when adding objects to the system.
+
+        Notes
+        =====
+
+        This method is not guaranteed to be backwards compatible as it may
+        improve over time. The method can become both more and less strict in
+        certain areas. However a well-defined system should always pass all
+        these tests.
+
+        """
+        msgs = []
+        # Save some data in variables
+        n_hc = self.holonomic_constraints.shape[0]
+        n_vc = self.velocity_constraints.shape[0]
+        n_q_dep, n_u_dep = self.q_dep.shape[0], self.u_dep.shape[0]
+        q_set, u_set = set(self.q), set(self.u)
+        n_q, n_u = len(q_set), len(u_set)
+        # Check number of holonomic constraints
+        if n_q_dep != n_hc:
+            msgs.append(filldedent(f"""
+            The number of dependent generalized coordinates {n_q_dep} should be
+            equal to the number of holonomic constraints {n_hc}."""))
+        # Check if all joint coordinates and speeds are present
+        missing_q = set()
+        for joint in self.joints:
+            missing_q.update(set(joint.coordinates).difference(q_set))
+        if missing_q:
+            msgs.append(filldedent(f"""
+            The generalized coordinates {missing_q} used in joints are not added
+            to the system."""))
+        # Method dependent checks
+        if issubclass(eom_method, KanesMethod):
+            n_kdes = len(self.kdes)
+            missing_kdes, missing_u = set(), set()
+            for joint in self.joints:
+                missing_u.update(set(joint.speeds).difference(u_set))
+                missing_kdes.update(set(joint.kdes).difference(
+                    self.kdes[:] + (-self.kdes)[:]))
+            if missing_u:
+                msgs.append(filldedent(f"""
+                The generalized speeds {missing_u} used in joints are not added
+                to the system."""))
+            if missing_kdes:
+                msgs.append(filldedent(f"""
+                The kinematic differential equations {missing_kdes} used in
+                joints are not added to the system."""))
+            if n_u_dep != n_vc:
+                msgs.append(filldedent(f"""
+                The number of dependent generalized speeds {n_u_dep} should be
+                equal to the number of velocity constraints {n_vc}."""))
+            if n_q > n_u:
+                msgs.append(filldedent(f"""
+                The number of generalized coordinates {n_q} should be less than
+                or equal to the number of generalized speeds {n_u}."""))
+            if n_u != n_kdes:
+                msgs.append(filldedent(f"""
+                The number of generalized speeds {n_u} should be equal to the
+                number of kinematic differential equations {n_kdes}."""))
+        elif issubclass(eom_method, LagrangesMethod):
+            not_qdots = set(self.u).difference(self.q.diff(dynamicsymbols._t))
+            for joint in self.joints:
+                not_qdots.update(set(
+                    joint.speeds).difference(self.q.diff(dynamicsymbols._t)))
+            if not_qdots:
+                msgs.append(filldedent(f"""
+                The generalized speeds {not_qdots} are not supported by this
+                method. Only derivatives of the generalized coordinates are
+                supported. If these symbols are used in your expressions, then
+                this will result in wrong equations of motion."""))
+            if self.u_aux:
+                msgs.append(filldedent(f"""
+                This method does not support auxiliary speeds. If these symbols
+                are used in your expressions, then this will result in wrong
+                equations of motion. The auxiliary speeds are {self.u_aux}."""))
+        else:
+            raise NotImplementedError(f'{eom_method} has not been implemented.')
+        if check_duplicates:  # Should be redundant
+            duplicates_to_check = [('generalized coordinates', self.q),
+                                   ('generalized speeds', self.u),
+                                   ('auxiliary speeds', self.u_aux),
+                                   ('bodies', self.bodies),
+                                   ('joints', self.joints)]
+            for name, lst in duplicates_to_check:
+                seen = set()
+                duplicates = {x for x in lst if x in seen or seen.add(x)}
+                if duplicates:
+                    msgs.append(filldedent(f"""
+                    The {name} {duplicates} exist multiple times within the
+                    system."""))
+        if msgs:
+            raise ValueError('\n'.join(msgs))
+
+
+class SymbolicSystem:
+    """SymbolicSystem is a class that contains all the information about a
+    system in a symbolic format such as the equations of motions and the bodies
+    and loads in the system.
+
+    There are three ways that the equations of motion can be described for
+    Symbolic System:
+
+
+        [1] Explicit form where the kinematics and dynamics are combined
+            x' = F_1(x, t, r, p)
+
+        [2] Implicit form where the kinematics and dynamics are combined
+            M_2(x, p) x' = F_2(x, t, r, p)
+
+        [3] Implicit form where the kinematics and dynamics are separate
+            M_3(q, p) u' = F_3(q, u, t, r, p)
+            q' = G(q, u, t, r, p)
+
+    where
+
+    x : states, e.g. [q, u]
+    t : time
+    r : specified (exogenous) inputs
+    p : constants
+    q : generalized coordinates
+    u : generalized speeds
+    F_1 : right hand side of the combined equations in explicit form
+    F_2 : right hand side of the combined equations in implicit form
+    F_3 : right hand side of the dynamical equations in implicit form
+    M_2 : mass matrix of the combined equations in implicit form
+    M_3 : mass matrix of the dynamical equations in implicit form
+    G : right hand side of the kinematical differential equations
+
+        Parameters
+        ==========
+
+        coord_states : ordered iterable of functions of time
+            This input will either be a collection of the coordinates or states
+            of the system depending on whether or not the speeds are also
+            given. If speeds are specified this input will be assumed to
+            be the coordinates otherwise this input will be assumed to
+            be the states.
+
+        right_hand_side : Matrix
+            This variable is the right hand side of the equations of motion in
+            any of the forms. The specific form will be assumed depending on
+            whether a mass matrix or coordinate derivatives are given.
+
+        speeds : ordered iterable of functions of time, optional
+            This is a collection of the generalized speeds of the system. If
+            given it will be assumed that the first argument (coord_states)
+            will represent the generalized coordinates of the system.
+
+        mass_matrix : Matrix, optional
+            The matrix of the implicit forms of the equations of motion (forms
+            [2] and [3]). The distinction between the forms is determined by
+            whether or not the coordinate derivatives are passed in. If
+            they are given form [3] will be assumed otherwise form [2] is
+            assumed.
+
+        coordinate_derivatives : Matrix, optional
+            The right hand side of the kinematical equations in explicit form.
+            If given it will be assumed that the equations of motion are being
+            entered in form [3].
+
+        alg_con : Iterable, optional
+            The indexes of the rows in the equations of motion that contain
+            algebraic constraints instead of differential equations. If the
+            equations are input in form [3], it will be assumed the indexes are
+            referencing the mass_matrix/right_hand_side combination and not the
+            coordinate_derivatives.
+
+        output_eqns : Dictionary, optional
+            Any output equations that are desired to be tracked are stored in a
+            dictionary where the key corresponds to the name given for the
+            specific equation and the value is the equation itself in symbolic
+            form
+
+        coord_idxs : Iterable, optional
+            If coord_states corresponds to the states rather than the
+            coordinates this variable will tell SymbolicSystem which indexes of
+            the states correspond to generalized coordinates.
+
+        speed_idxs : Iterable, optional
+            If coord_states corresponds to the states rather than the
+            coordinates this variable will tell SymbolicSystem which indexes of
+            the states correspond to generalized speeds.
+
+        bodies : iterable of Body/Rigidbody objects, optional
+            Iterable containing the bodies of the system
+
+        loads : iterable of load instances (described below), optional
+            Iterable containing the loads of the system where forces are given
+            by (point of application, force vector) and torques are given by
+            (reference frame acting upon, torque vector). Ex [(point, force),
+            (ref_frame, torque)]
+
+    Attributes
+    ==========
+
+    coordinates : Matrix, shape(n, 1)
+        This is a matrix containing the generalized coordinates of the system
+
+    speeds : Matrix, shape(m, 1)
+        This is a matrix containing the generalized speeds of the system
+
+    states : Matrix, shape(o, 1)
+        This is a matrix containing the state variables of the system
+
+    alg_con : List
+        This list contains the indices of the algebraic constraints in the
+        combined equations of motion. The presence of these constraints
+        requires that a DAE solver be used instead of an ODE solver.
+        If the system is given in form [3] the alg_con variable will be
+        adjusted such that it is a representation of the combined kinematics
+        and dynamics thus make sure it always matches the mass matrix
+        entered.
+
+    dyn_implicit_mat : Matrix, shape(m, m)
+        This is the M matrix in form [3] of the equations of motion (the mass
+        matrix or generalized inertia matrix of the dynamical equations of
+        motion in implicit form).
+
+    dyn_implicit_rhs : Matrix, shape(m, 1)
+        This is the F vector in form [3] of the equations of motion (the right
+        hand side of the dynamical equations of motion in implicit form).
+
+    comb_implicit_mat : Matrix, shape(o, o)
+        This is the M matrix in form [2] of the equations of motion.
+        This matrix contains a block diagonal structure where the top
+        left block (the first rows) represent the matrix in the
+        implicit form of the kinematical equations and the bottom right
+        block (the last rows) represent the matrix in the implicit form
+        of the dynamical equations.
+
+    comb_implicit_rhs : Matrix, shape(o, 1)
+        This is the F vector in form [2] of the equations of motion. The top
+        part of the vector represents the right hand side of the implicit form
+        of the kinemaical equations and the bottom of the vector represents the
+        right hand side of the implicit form of the dynamical equations of
+        motion.
+
+    comb_explicit_rhs : Matrix, shape(o, 1)
+        This vector represents the right hand side of the combined equations of
+        motion in explicit form (form [1] from above).
+
+    kin_explicit_rhs : Matrix, shape(m, 1)
+        This is the right hand side of the explicit form of the kinematical
+        equations of motion as can be seen in form [3] (the G matrix).
+
+    output_eqns : Dictionary
+        If output equations were given they are stored in a dictionary where
+        the key corresponds to the name given for the specific equation and
+        the value is the equation itself in symbolic form
+
+    bodies : Tuple
+        If the bodies in the system were given they are stored in a tuple for
+        future access
+
+    loads : Tuple
+        If the loads in the system were given they are stored in a tuple for
+        future access. This includes forces and torques where forces are given
+        by (point of application, force vector) and torques are given by
+        (reference frame acted upon, torque vector).
+
+    Example
+    =======
+
+    As a simple example, the dynamics of a simple pendulum will be input into a
+    SymbolicSystem object manually. First some imports will be needed and then
+    symbols will be set up for the length of the pendulum (l), mass at the end
+    of the pendulum (m), and a constant for gravity (g). ::
+
+        >>> from sympy import Matrix, sin, symbols
+        >>> from sympy.physics.mechanics import dynamicsymbols, SymbolicSystem
+        >>> l, m, g = symbols('l m g')
+
+    The system will be defined by an angle of theta from the vertical and a
+    generalized speed of omega will be used where omega = theta_dot. ::
+
+        >>> theta, omega = dynamicsymbols('theta omega')
+
+    Now the equations of motion are ready to be formed and passed to the
+    SymbolicSystem object. ::
+
+        >>> kin_explicit_rhs = Matrix([omega])
+        >>> dyn_implicit_mat = Matrix([l**2 * m])
+        >>> dyn_implicit_rhs = Matrix([-g * l * m * sin(theta)])
+        >>> symsystem = SymbolicSystem([theta], dyn_implicit_rhs, [omega],
+        ...                            dyn_implicit_mat)
+
+    Notes
+    =====
+
+    m : number of generalized speeds
+    n : number of generalized coordinates
+    o : number of states
+
+    """
+
+    def __init__(self, coord_states, right_hand_side, speeds=None,
+                 mass_matrix=None, coordinate_derivatives=None, alg_con=None,
+                 output_eqns={}, coord_idxs=None, speed_idxs=None, bodies=None,
+                 loads=None):
+        """Initializes a SymbolicSystem object"""
+
+        # Extract information on speeds, coordinates and states
+        if speeds is None:
+            self._states = Matrix(coord_states)
+
+            if coord_idxs is None:
+                self._coordinates = None
+            else:
+                coords = [coord_states[i] for i in coord_idxs]
+                self._coordinates = Matrix(coords)
+
+            if speed_idxs is None:
+                self._speeds = None
+            else:
+                speeds_inter = [coord_states[i] for i in speed_idxs]
+                self._speeds = Matrix(speeds_inter)
+        else:
+            self._coordinates = Matrix(coord_states)
+            self._speeds = Matrix(speeds)
+            self._states = self._coordinates.col_join(self._speeds)
+
+        # Extract equations of motion form
+        if coordinate_derivatives is not None:
+            self._kin_explicit_rhs = coordinate_derivatives
+            self._dyn_implicit_rhs = right_hand_side
+            self._dyn_implicit_mat = mass_matrix
+            self._comb_implicit_rhs = None
+            self._comb_implicit_mat = None
+            self._comb_explicit_rhs = None
+        elif mass_matrix is not None:
+            self._kin_explicit_rhs = None
+            self._dyn_implicit_rhs = None
+            self._dyn_implicit_mat = None
+            self._comb_implicit_rhs = right_hand_side
+            self._comb_implicit_mat = mass_matrix
+            self._comb_explicit_rhs = None
+        else:
+            self._kin_explicit_rhs = None
+            self._dyn_implicit_rhs = None
+            self._dyn_implicit_mat = None
+            self._comb_implicit_rhs = None
+            self._comb_implicit_mat = None
+            self._comb_explicit_rhs = right_hand_side
+
+        # Set the remainder of the inputs as instance attributes
+        if alg_con is not None and coordinate_derivatives is not None:
+            alg_con = [i + len(coordinate_derivatives) for i in alg_con]
+        self._alg_con = alg_con
+        self.output_eqns = output_eqns
+
+        # Change the body and loads iterables to tuples if they are not tuples
+        # already
+        if not isinstance(bodies, tuple) and bodies is not None:
+            bodies = tuple(bodies)
+        if not isinstance(loads, tuple) and loads is not None:
+            loads = tuple(loads)
+        self._bodies = bodies
+        self._loads = loads
+
+    @property
+    def coordinates(self):
+        """Returns the column matrix of the generalized coordinates"""
+        if self._coordinates is None:
+            raise AttributeError("The coordinates were not specified.")
+        else:
+            return self._coordinates
+
+    @property
+    def speeds(self):
+        """Returns the column matrix of generalized speeds"""
+        if self._speeds is None:
+            raise AttributeError("The speeds were not specified.")
+        else:
+            return self._speeds
+
+    @property
+    def states(self):
+        """Returns the column matrix of the state variables"""
+        return self._states
+
+    @property
+    def alg_con(self):
+        """Returns a list with the indices of the rows containing algebraic
+        constraints in the combined form of the equations of motion"""
+        return self._alg_con
+
+    @property
+    def dyn_implicit_mat(self):
+        """Returns the matrix, M, corresponding to the dynamic equations in
+        implicit form, M x' = F, where the kinematical equations are not
+        included"""
+        if self._dyn_implicit_mat is None:
+            raise AttributeError("dyn_implicit_mat is not specified for "
+                                 "equations of motion form [1] or [2].")
+        else:
+            return self._dyn_implicit_mat
+
+    @property
+    def dyn_implicit_rhs(self):
+        """Returns the column matrix, F, corresponding to the dynamic equations
+        in implicit form, M x' = F, where the kinematical equations are not
+        included"""
+        if self._dyn_implicit_rhs is None:
+            raise AttributeError("dyn_implicit_rhs is not specified for "
+                                 "equations of motion form [1] or [2].")
+        else:
+            return self._dyn_implicit_rhs
+
+    @property
+    def comb_implicit_mat(self):
+        """Returns the matrix, M, corresponding to the equations of motion in
+        implicit form (form [2]), M x' = F, where the kinematical equations are
+        included"""
+        if self._comb_implicit_mat is None:
+            if self._dyn_implicit_mat is not None:
+                num_kin_eqns = len(self._kin_explicit_rhs)
+                num_dyn_eqns = len(self._dyn_implicit_rhs)
+                zeros1 = zeros(num_kin_eqns, num_dyn_eqns)
+                zeros2 = zeros(num_dyn_eqns, num_kin_eqns)
+                inter1 = eye(num_kin_eqns).row_join(zeros1)
+                inter2 = zeros2.row_join(self._dyn_implicit_mat)
+                self._comb_implicit_mat = inter1.col_join(inter2)
+                return self._comb_implicit_mat
+            else:
+                raise AttributeError("comb_implicit_mat is not specified for "
+                                     "equations of motion form [1].")
+        else:
+            return self._comb_implicit_mat
+
+    @property
+    def comb_implicit_rhs(self):
+        """Returns the column matrix, F, corresponding to the equations of
+        motion in implicit form (form [2]), M x' = F, where the kinematical
+        equations are included"""
+        if self._comb_implicit_rhs is None:
+            if self._dyn_implicit_rhs is not None:
+                kin_inter = self._kin_explicit_rhs
+                dyn_inter = self._dyn_implicit_rhs
+                self._comb_implicit_rhs = kin_inter.col_join(dyn_inter)
+                return self._comb_implicit_rhs
+            else:
+                raise AttributeError("comb_implicit_mat is not specified for "
+                                     "equations of motion in form [1].")
+        else:
+            return self._comb_implicit_rhs
+
+    def compute_explicit_form(self):
+        """If the explicit right hand side of the combined equations of motion
+        is to provided upon initialization, this method will calculate it. This
+        calculation can potentially take awhile to compute."""
+        if self._comb_explicit_rhs is not None:
+            raise AttributeError("comb_explicit_rhs is already formed.")
+
+        inter1 = getattr(self, 'kin_explicit_rhs', None)
+        if inter1 is not None:
+            inter2 = self._dyn_implicit_mat.LUsolve(self._dyn_implicit_rhs)
+            out = inter1.col_join(inter2)
+        else:
+            out = self._comb_implicit_mat.LUsolve(self._comb_implicit_rhs)
+
+        self._comb_explicit_rhs = out
+
+    @property
+    def comb_explicit_rhs(self):
+        """Returns the right hand side of the equations of motion in explicit
+        form, x' = F, where the kinematical equations are included"""
+        if self._comb_explicit_rhs is None:
+            raise AttributeError("Please run .combute_explicit_form before "
+                                 "attempting to access comb_explicit_rhs.")
+        else:
+            return self._comb_explicit_rhs
+
+    @property
+    def kin_explicit_rhs(self):
+        """Returns the right hand side of the kinematical equations in explicit
+        form, q' = G"""
+        if self._kin_explicit_rhs is None:
+            raise AttributeError("kin_explicit_rhs is not specified for "
+                                 "equations of motion form [1] or [2].")
+        else:
+            return self._kin_explicit_rhs
+
+    def dynamic_symbols(self):
+        """Returns a column matrix containing all of the symbols in the system
+        that depend on time"""
+        # Create a list of all of the expressions in the equations of motion
+        if self._comb_explicit_rhs is None:
+            eom_expressions = (self.comb_implicit_mat[:] +
+                               self.comb_implicit_rhs[:])
+        else:
+            eom_expressions = (self._comb_explicit_rhs[:])
+
+        functions_of_time = set()
+        for expr in eom_expressions:
+            functions_of_time = functions_of_time.union(
+                find_dynamicsymbols(expr))
+        functions_of_time = functions_of_time.union(self._states)
+
+        return tuple(functions_of_time)
+
+    def constant_symbols(self):
+        """Returns a column matrix containing all of the symbols in the system
+        that do not depend on time"""
+        # Create a list of all of the expressions in the equations of motion
+        if self._comb_explicit_rhs is None:
+            eom_expressions = (self.comb_implicit_mat[:] +
+                               self.comb_implicit_rhs[:])
+        else:
+            eom_expressions = (self._comb_explicit_rhs[:])
+
+        constants = set()
+        for expr in eom_expressions:
+            constants = constants.union(expr.free_symbols)
+        constants.remove(dynamicsymbols._t)
+
+        return tuple(constants)
+
+    @property
+    def bodies(self):
+        """Returns the bodies in the system"""
+        if self._bodies is None:
+            raise AttributeError("bodies were not specified for the system.")
+        else:
+            return self._bodies
+
+    @property
+    def loads(self):
+        """Returns the loads in the system"""
+        if self._loads is None:
+            raise AttributeError("loads were not specified for the system.")
+        else:
+            return self._loads

lib/python3.12/site-packages/sympy/physics/mechanics/wrapping_geometry.py

@@ -0,0 +1,641 @@
+"""Geometry objects for use by wrapping pathways."""
+
+from abc import ABC, abstractmethod
+
+from sympy import Integer, acos, pi, sqrt, sympify, tan
+from sympy.core.relational import Eq
+from sympy.functions.elementary.trigonometric import atan2
+from sympy.polys.polytools import cancel
+from sympy.physics.vector import Vector, dot
+from sympy.simplify.simplify import trigsimp
+
+
+__all__ = [
+    'WrappingGeometryBase',
+    'WrappingCylinder',
+    'WrappingSphere',
+]
+
+
+class WrappingGeometryBase(ABC):
+    """Abstract base class for all geometry classes to inherit from.
+
+    Notes
+    =====
+
+    Instances of this class cannot be directly instantiated by users. However,
+    it can be used to created custom geometry types through subclassing.
+
+    """
+
+    @property
+    @abstractmethod
+    def point(cls):
+        """The point with which the geometry is associated."""
+        pass
+
+    @abstractmethod
+    def point_on_surface(self, point):
+        """Returns ``True`` if a point is on the geometry's surface.
+
+        Parameters
+        ==========
+        point : Point
+            The point for which it's to be ascertained if it's on the
+            geometry's surface or not.
+
+        """
+        pass
+
+    @abstractmethod
+    def geodesic_length(self, point_1, point_2):
+        """Returns the shortest distance between two points on a geometry's
+        surface.
+
+        Parameters
+        ==========
+
+        point_1 : Point
+            The point from which the geodesic length should be calculated.
+        point_2 : Point
+            The point to which the geodesic length should be calculated.
+
+        """
+        pass
+
+    @abstractmethod
+    def geodesic_end_vectors(self, point_1, point_2):
+        """The vectors parallel to the geodesic at the two end points.
+
+        Parameters
+        ==========
+
+        point_1 : Point
+            The point from which the geodesic originates.
+        point_2 : Point
+            The point at which the geodesic terminates.
+
+        """
+        pass
+
+    def __repr__(self):
+        """Default representation of a geometry object."""
+        return f'{self.__class__.__name__}()'
+
+
+class WrappingSphere(WrappingGeometryBase):
+    """A solid spherical object.
+
+    Explanation
+    ===========
+
+    A wrapping geometry that allows for circular arcs to be defined between
+    pairs of points. These paths are always geodetic (the shortest possible).
+
+    Examples
+    ========
+
+    To create a ``WrappingSphere`` instance, a ``Symbol`` denoting its radius
+    and ``Point`` at which its center will be located are needed:
+
+    >>> from sympy import symbols
+    >>> from sympy.physics.mechanics import Point, WrappingSphere
+    >>> r = symbols('r')
+    >>> pO = Point('pO')
+
+    A sphere with radius ``r`` centered on ``pO`` can be instantiated with:
+
+    >>> WrappingSphere(r, pO)
+    WrappingSphere(radius=r, point=pO)
+
+    Parameters
+    ==========
+
+    radius : Symbol
+        Radius of the sphere. This symbol must represent a value that is
+        positive and constant, i.e. it cannot be a dynamic symbol, nor can it
+        be an expression.
+    point : Point
+        A point at which the sphere is centered.
+
+    See Also
+    ========
+
+    WrappingCylinder: Cylindrical geometry where the wrapping direction can be
+        defined.
+
+    """
+
+    def __init__(self, radius, point):
+        """Initializer for ``WrappingSphere``.
+
+        Parameters
+        ==========
+
+        radius : Symbol
+            The radius of the sphere.
+        point : Point
+            A point on which the sphere is centered.
+
+        """
+        self.radius = radius
+        self.point = point
+
+    @property
+    def radius(self):
+        """Radius of the sphere."""
+        return self._radius
+
+    @radius.setter
+    def radius(self, radius):
+        self._radius = radius
+
+    @property
+    def point(self):
+        """A point on which the sphere is centered."""
+        return self._point
+
+    @point.setter
+    def point(self, point):
+        self._point = point
+
+    def point_on_surface(self, point):
+        """Returns ``True`` if a point is on the sphere's surface.
+
+        Parameters
+        ==========
+
+        point : Point
+            The point for which it's to be ascertained if it's on the sphere's
+            surface or not. This point's position relative to the sphere's
+            center must be a simple expression involving the radius of the
+            sphere, otherwise this check will likely not work.
+
+        """
+        point_vector = point.pos_from(self.point)
+        if isinstance(point_vector, Vector):
+            point_radius_squared = dot(point_vector, point_vector)
+        else:
+            point_radius_squared = point_vector**2
+        return Eq(point_radius_squared, self.radius**2) == True
+
+    def geodesic_length(self, point_1, point_2):
+        r"""Returns the shortest distance between two points on the sphere's
+        surface.
+
+        Explanation
+        ===========
+
+        The geodesic length, i.e. the shortest arc along the surface of a
+        sphere, connecting two points can be calculated using the formula:
+
+        .. math::
+
+           l = \arccos\left(\mathbf{v}_1 \cdot \mathbf{v}_2\right)
+
+        where $\mathbf{v}_1$ and $\mathbf{v}_2$ are the unit vectors from the
+        sphere's center to the first and second points on the sphere's surface
+        respectively. Note that the actual path that the geodesic will take is
+        undefined when the two points are directly opposite one another.
+
+        Examples
+        ========
+
+        A geodesic length can only be calculated between two points on the
+        sphere's surface. Firstly, a ``WrappingSphere`` instance must be
+        created along with two points that will lie on its surface:
+
+        >>> from sympy import symbols
+        >>> from sympy.physics.mechanics import (Point, ReferenceFrame,
+        ...     WrappingSphere)
+        >>> N = ReferenceFrame('N')
+        >>> r = symbols('r')
+        >>> pO = Point('pO')
+        >>> pO.set_vel(N, 0)
+        >>> sphere = WrappingSphere(r, pO)
+        >>> p1 = Point('p1')
+        >>> p2 = Point('p2')
+
+        Let's assume that ``p1`` lies at a distance of ``r`` in the ``N.x``
+        direction from ``pO`` and that ``p2`` is located on the sphere's
+        surface in the ``N.y + N.z`` direction from ``pO``. These positions can
+        be set with:
+
+        >>> p1.set_pos(pO, r*N.x)
+        >>> p1.pos_from(pO)
+        r*N.x
+        >>> p2.set_pos(pO, r*(N.y + N.z).normalize())
+        >>> p2.pos_from(pO)
+        sqrt(2)*r/2*N.y + sqrt(2)*r/2*N.z
+
+        The geodesic length, which is in this case is a quarter of the sphere's
+        circumference, can be calculated using the ``geodesic_length`` method:
+
+        >>> sphere.geodesic_length(p1, p2)
+        pi*r/2
+
+        If the ``geodesic_length`` method is passed an argument, the ``Point``
+        that doesn't lie on the sphere's surface then a ``ValueError`` is
+        raised because it's not possible to calculate a value in this case.
+
+        Parameters
+        ==========
+
+        point_1 : Point
+            Point from which the geodesic length should be calculated.
+        point_2 : Point
+            Point to which the geodesic length should be calculated.
+
+        """
+        for point in (point_1, point_2):
+            if not self.point_on_surface(point):
+                msg = (
+                    f'Geodesic length cannot be calculated as point {point} '
+                    f'with radius {point.pos_from(self.point).magnitude()} '
+                    f'from the sphere\'s center {self.point} does not lie on '
+                    f'the surface of {self} with radius {self.radius}.'
+                )
+                raise ValueError(msg)
+        point_1_vector = point_1.pos_from(self.point).normalize()
+        point_2_vector = point_2.pos_from(self.point).normalize()
+        central_angle = acos(point_2_vector.dot(point_1_vector))
+        geodesic_length = self.radius*central_angle
+        return geodesic_length
+
+    def geodesic_end_vectors(self, point_1, point_2):
+        """The vectors parallel to the geodesic at the two end points.
+
+        Parameters
+        ==========
+
+        point_1 : Point
+            The point from which the geodesic originates.
+        point_2 : Point
+            The point at which the geodesic terminates.
+
+        """
+        pA, pB = point_1, point_2
+        pO = self.point
+        pA_vec = pA.pos_from(pO)
+        pB_vec = pB.pos_from(pO)
+
+        if pA_vec.cross(pB_vec) == 0:
+            msg = (
+                f'Can\'t compute geodesic end vectors for the pair of points '
+                f'{pA} and {pB} on a sphere {self} as they are diametrically '
+                f'opposed, thus the geodesic is not defined.'
+            )
+            raise ValueError(msg)
+
+        return (
+            pA_vec.cross(pB.pos_from(pA)).cross(pA_vec).normalize(),
+            pB_vec.cross(pA.pos_from(pB)).cross(pB_vec).normalize(),
+        )
+
+    def __repr__(self):
+        """Representation of a ``WrappingSphere``."""
+        return (
+            f'{self.__class__.__name__}(radius={self.radius}, '
+            f'point={self.point})'
+        )
+
+
+class WrappingCylinder(WrappingGeometryBase):
+    """A solid (infinite) cylindrical object.
+
+    Explanation
+    ===========
+
+    A wrapping geometry that allows for circular arcs to be defined between
+    pairs of points. These paths are always geodetic (the shortest possible) in
+    the sense that they will be a straight line on the unwrapped cylinder's
+    surface. However, it is also possible for a direction to be specified, i.e.
+    paths can be influenced such that they either wrap along the shortest side
+    or the longest side of the cylinder. To define these directions, rotations
+    are in the positive direction following the right-hand rule.
+
+    Examples
+    ========
+
+    To create a ``WrappingCylinder`` instance, a ``Symbol`` denoting its
+    radius, a ``Vector`` defining its axis, and a ``Point`` through which its
+    axis passes are needed:
+
+    >>> from sympy import symbols
+    >>> from sympy.physics.mechanics import (Point, ReferenceFrame,
+    ...     WrappingCylinder)
+    >>> N = ReferenceFrame('N')
+    >>> r = symbols('r')
+    >>> pO = Point('pO')
+    >>> ax = N.x
+
+    A cylinder with radius ``r``, and axis parallel to ``N.x`` passing through
+    ``pO`` can be instantiated with:
+
+    >>> WrappingCylinder(r, pO, ax)
+    WrappingCylinder(radius=r, point=pO, axis=N.x)
+
+    Parameters
+    ==========
+
+    radius : Symbol
+        The radius of the cylinder.
+    point : Point
+        A point through which the cylinder's axis passes.
+    axis : Vector
+        The axis along which the cylinder is aligned.
+
+    See Also
+    ========
+
+    WrappingSphere: Spherical geometry where the wrapping direction is always
+        geodetic.
+
+    """
+
+    def __init__(self, radius, point, axis):
+        """Initializer for ``WrappingCylinder``.
+
+        Parameters
+        ==========
+
+        radius : Symbol
+            The radius of the cylinder. This symbol must represent a value that
+            is positive and constant, i.e. it cannot be a dynamic symbol.
+        point : Point
+            A point through which the cylinder's axis passes.
+        axis : Vector
+            The axis along which the cylinder is aligned.
+
+        """
+        self.radius = radius
+        self.point = point
+        self.axis = axis
+
+    @property
+    def radius(self):
+        """Radius of the cylinder."""
+        return self._radius
+
+    @radius.setter
+    def radius(self, radius):
+        self._radius = radius
+
+    @property
+    def point(self):
+        """A point through which the cylinder's axis passes."""
+        return self._point
+
+    @point.setter
+    def point(self, point):
+        self._point = point
+
+    @property
+    def axis(self):
+        """Axis along which the cylinder is aligned."""
+        return self._axis
+
+    @axis.setter
+    def axis(self, axis):
+        self._axis = axis.normalize()
+
+    def point_on_surface(self, point):
+        """Returns ``True`` if a point is on the cylinder's surface.
+
+        Parameters
+        ==========
+
+        point : Point
+            The point for which it's to be ascertained if it's on the
+            cylinder's surface or not. This point's position relative to the
+            cylinder's axis must be a simple expression involving the radius of
+            the sphere, otherwise this check will likely not work.
+
+        """
+        relative_position = point.pos_from(self.point)
+        parallel = relative_position.dot(self.axis) * self.axis
+        point_vector = relative_position - parallel
+        if isinstance(point_vector, Vector):
+            point_radius_squared = dot(point_vector, point_vector)
+        else:
+            point_radius_squared = point_vector**2
+        return Eq(trigsimp(point_radius_squared), self.radius**2) == True
+
+    def geodesic_length(self, point_1, point_2):
+        """The shortest distance between two points on a geometry's surface.
+
+        Explanation
+        ===========
+
+        The geodesic length, i.e. the shortest arc along the surface of a
+        cylinder, connecting two points. It can be calculated using Pythagoras'
+        theorem. The first short side is the distance between the two points on
+        the cylinder's surface parallel to the cylinder's axis. The second
+        short side is the arc of a circle between the two points of the
+        cylinder's surface perpendicular to the cylinder's axis. The resulting
+        hypotenuse is the geodesic length.
+
+        Examples
+        ========
+
+        A geodesic length can only be calculated between two points on the
+        cylinder's surface. Firstly, a ``WrappingCylinder`` instance must be
+        created along with two points that will lie on its surface:
+
+        >>> from sympy import symbols, cos, sin
+        >>> from sympy.physics.mechanics import (Point, ReferenceFrame,
+        ...     WrappingCylinder, dynamicsymbols)
+        >>> N = ReferenceFrame('N')
+        >>> r = symbols('r')
+        >>> pO = Point('pO')
+        >>> pO.set_vel(N, 0)
+        >>> cylinder = WrappingCylinder(r, pO, N.x)
+        >>> p1 = Point('p1')
+        >>> p2 = Point('p2')
+
+        Let's assume that ``p1`` is located at ``N.x + r*N.y`` relative to
+        ``pO`` and that ``p2`` is located at ``r*(cos(q)*N.y + sin(q)*N.z)``
+        relative to ``pO``, where ``q(t)`` is a generalized coordinate
+        specifying the angle rotated around the ``N.x`` axis according to the
+        right-hand rule where ``N.y`` is zero. These positions can be set with:
+
+        >>> q = dynamicsymbols('q')
+        >>> p1.set_pos(pO, N.x + r*N.y)
+        >>> p1.pos_from(pO)
+        N.x + r*N.y
+        >>> p2.set_pos(pO, r*(cos(q)*N.y + sin(q)*N.z).normalize())
+        >>> p2.pos_from(pO).simplify()
+        r*cos(q(t))*N.y + r*sin(q(t))*N.z
+
+        The geodesic length, which is in this case a is the hypotenuse of a
+        right triangle where the other two side lengths are ``1`` (parallel to
+        the cylinder's axis) and ``r*q(t)`` (parallel to the cylinder's cross
+        section), can be calculated using the ``geodesic_length`` method:
+
+        >>> cylinder.geodesic_length(p1, p2).simplify()
+        sqrt(r**2*q(t)**2 + 1)
+
+        If the ``geodesic_length`` method is passed an argument ``Point`` that
+        doesn't lie on the sphere's surface then a ``ValueError`` is raised
+        because it's not possible to calculate a value in this case.
+
+        Parameters
+        ==========
+
+        point_1 : Point
+            Point from which the geodesic length should be calculated.
+        point_2 : Point
+            Point to which the geodesic length should be calculated.
+
+        """
+        for point in (point_1, point_2):
+            if not self.point_on_surface(point):
+                msg = (
+                    f'Geodesic length cannot be calculated as point {point} '
+                    f'with radius {point.pos_from(self.point).magnitude()} '
+                    f'from the cylinder\'s center {self.point} does not lie on '
+                    f'the surface of {self} with radius {self.radius} and axis '
+                    f'{self.axis}.'
+                )
+                raise ValueError(msg)
+
+        relative_position = point_2.pos_from(point_1)
+        parallel_length = relative_position.dot(self.axis)
+
+        point_1_relative_position = point_1.pos_from(self.point)
+        point_1_perpendicular_vector = (
+            point_1_relative_position
+            - point_1_relative_position.dot(self.axis)*self.axis
+        ).normalize()
+
+        point_2_relative_position = point_2.pos_from(self.point)
+        point_2_perpendicular_vector = (
+            point_2_relative_position
+            - point_2_relative_position.dot(self.axis)*self.axis
+        ).normalize()
+
+        central_angle = _directional_atan(
+            cancel(point_1_perpendicular_vector
+                .cross(point_2_perpendicular_vector)
+                .dot(self.axis)),
+            cancel(point_1_perpendicular_vector.dot(point_2_perpendicular_vector)),
+        )
+
+        planar_arc_length = self.radius*central_angle
+        geodesic_length = sqrt(parallel_length**2 + planar_arc_length**2)
+        return geodesic_length
+
+    def geodesic_end_vectors(self, point_1, point_2):
+        """The vectors parallel to the geodesic at the two end points.
+
+        Parameters
+        ==========
+
+        point_1 : Point
+            The point from which the geodesic originates.
+        point_2 : Point
+            The point at which the geodesic terminates.
+
+        """
+        point_1_from_origin_point = point_1.pos_from(self.point)
+        point_2_from_origin_point = point_2.pos_from(self.point)
+
+        if point_1_from_origin_point == point_2_from_origin_point:
+            msg = (
+                f'Cannot compute geodesic end vectors for coincident points '
+                f'{point_1} and {point_2} as no geodesic exists.'
+            )
+            raise ValueError(msg)
+
+        point_1_parallel = point_1_from_origin_point.dot(self.axis) * self.axis
+        point_2_parallel = point_2_from_origin_point.dot(self.axis) * self.axis
+        point_1_normal = (point_1_from_origin_point - point_1_parallel)
+        point_2_normal = (point_2_from_origin_point - point_2_parallel)
+
+        if point_1_normal == point_2_normal:
+            point_1_perpendicular = Vector(0)
+            point_2_perpendicular = Vector(0)
+        else:
+            point_1_perpendicular = self.axis.cross(point_1_normal).normalize()
+            point_2_perpendicular = -self.axis.cross(point_2_normal).normalize()
+
+        geodesic_length = self.geodesic_length(point_1, point_2)
+        relative_position = point_2.pos_from(point_1)
+        parallel_length = relative_position.dot(self.axis)
+        planar_arc_length = sqrt(geodesic_length**2 - parallel_length**2)
+
+        point_1_vector = (
+            planar_arc_length * point_1_perpendicular
+            + parallel_length * self.axis
+        ).normalize()
+        point_2_vector = (
+            planar_arc_length * point_2_perpendicular
+            - parallel_length * self.axis
+        ).normalize()
+
+        return (point_1_vector, point_2_vector)
+
+    def __repr__(self):
+        """Representation of a ``WrappingCylinder``."""
+        return (
+            f'{self.__class__.__name__}(radius={self.radius}, '
+            f'point={self.point}, axis={self.axis})'
+        )
+
+
+def _directional_atan(numerator, denominator):
+    """Compute atan in a directional sense as required for geodesics.
+
+    Explanation
+    ===========
+
+    To be able to control the direction of the geodesic length along the
+    surface of a cylinder a dedicated arctangent function is needed that
+    properly handles the directionality of different case. This function
+    ensures that the central angle is always positive but shifting the case
+    where ``atan2`` would return a negative angle to be centered around
+    ``2*pi``.
+
+    Notes
+    =====
+
+    This function only handles very specific cases, i.e. the ones that are
+    expected to be encountered when calculating symbolic geodesics on uniformly
+    curved surfaces. As such, ``NotImplemented`` errors can be raised in many
+    cases. This function is named with a leader underscore to indicate that it
+    only aims to provide very specific functionality within the private scope
+    of this module.
+
+    """
+
+    if numerator.is_number and denominator.is_number:
+        angle = atan2(numerator, denominator)
+        if angle < 0:
+            angle += 2 * pi
+    elif numerator.is_number:
+        msg = (
+            f'Cannot compute a directional atan when the numerator {numerator} '
+            f'is numeric and the denominator {denominator} is symbolic.'
+        )
+        raise NotImplementedError(msg)
+    elif denominator.is_number:
+        msg = (
+            f'Cannot compute a directional atan when the numerator {numerator} '
+            f'is symbolic and the denominator {denominator} is numeric.'
+        )
+        raise NotImplementedError(msg)
+    else:
+        ratio = sympify(trigsimp(numerator / denominator))
+        if isinstance(ratio, tan):
+            angle = ratio.args[0]
+        elif (
+            ratio.is_Mul
+            and ratio.args[0] == Integer(-1)
+            and isinstance(ratio.args[1], tan)
+        ):
+            angle = 2 * pi - ratio.args[1].args[0]
+        else:
+            msg = f'Cannot compute a directional atan for the value {ratio}.'
+            raise NotImplementedError(msg)
+
+    return angle

lib/python3.12/site-packages/sympy/physics/tests/test_physics_matrices.py

@@ -0,0 +1,84 @@
+from sympy.physics.matrices import msigma, mgamma, minkowski_tensor, pat_matrix, mdft
+from sympy.core.numbers import (I, Rational)
+from sympy.core.singleton import S
+from sympy.functions.elementary.miscellaneous import sqrt
+from sympy.matrices.dense import (Matrix, eye, zeros)
+from sympy.testing.pytest import warns_deprecated_sympy
+
+
+def test_parallel_axis_theorem():
+    # This tests the parallel axis theorem matrix by comparing to test
+    # matrices.
+
+    # First case, 1 in all directions.
+    mat1 = Matrix(((2, -1, -1), (-1, 2, -1), (-1, -1, 2)))
+    assert pat_matrix(1, 1, 1, 1) == mat1
+    assert pat_matrix(2, 1, 1, 1) == 2*mat1
+
+    # Second case, 1 in x, 0 in all others
+    mat2 = Matrix(((0, 0, 0), (0, 1, 0), (0, 0, 1)))
+    assert pat_matrix(1, 1, 0, 0) == mat2
+    assert pat_matrix(2, 1, 0, 0) == 2*mat2
+
+    # Third case, 1 in y, 0 in all others
+    mat3 = Matrix(((1, 0, 0), (0, 0, 0), (0, 0, 1)))
+    assert pat_matrix(1, 0, 1, 0) == mat3
+    assert pat_matrix(2, 0, 1, 0) == 2*mat3
+
+    # Fourth case, 1 in z, 0 in all others
+    mat4 = Matrix(((1, 0, 0), (0, 1, 0), (0, 0, 0)))
+    assert pat_matrix(1, 0, 0, 1) == mat4
+    assert pat_matrix(2, 0, 0, 1) == 2*mat4
+
+
+def test_Pauli():
+    #this and the following test are testing both Pauli and Dirac matrices
+    #and also that the general Matrix class works correctly in a real world
+    #situation
+    sigma1 = msigma(1)
+    sigma2 = msigma(2)
+    sigma3 = msigma(3)
+
+    assert sigma1 == sigma1
+    assert sigma1 != sigma2
+
+    # sigma*I -> I*sigma    (see #354)
+    assert sigma1*sigma2 == sigma3*I
+    assert sigma3*sigma1 == sigma2*I
+    assert sigma2*sigma3 == sigma1*I
+
+    assert sigma1*sigma1 == eye(2)
+    assert sigma2*sigma2 == eye(2)
+    assert sigma3*sigma3 == eye(2)
+
+    assert sigma1*2*sigma1 == 2*eye(2)
+    assert sigma1*sigma3*sigma1 == -sigma3
+
+
+def test_Dirac():
+    gamma0 = mgamma(0)
+    gamma1 = mgamma(1)
+    gamma2 = mgamma(2)
+    gamma3 = mgamma(3)
+    gamma5 = mgamma(5)
+
+    # gamma*I -> I*gamma    (see #354)
+    assert gamma5 == gamma0 * gamma1 * gamma2 * gamma3 * I
+    assert gamma1 * gamma2 + gamma2 * gamma1 == zeros(4)
+    assert gamma0 * gamma0 == eye(4) * minkowski_tensor[0, 0]
+    assert gamma2 * gamma2 != eye(4) * minkowski_tensor[0, 0]
+    assert gamma2 * gamma2 == eye(4) * minkowski_tensor[2, 2]
+
+    assert mgamma(5, True) == \
+        mgamma(0, True)*mgamma(1, True)*mgamma(2, True)*mgamma(3, True)*I
+
+def test_mdft():
+    with warns_deprecated_sympy():
+        assert mdft(1) == Matrix([[1]])
+    with warns_deprecated_sympy():
+        assert mdft(2) == 1/sqrt(2)*Matrix([[1,1],[1,-1]])
+    with warns_deprecated_sympy():
+        assert mdft(4) == Matrix([[S.Half,  S.Half,  S.Half, S.Half],
+                                  [S.Half, -I/2, Rational(-1,2),  I/2],
+                                  [S.Half, Rational(-1,2),  S.Half, Rational(-1,2)],
+                                  [S.Half,  I/2, Rational(-1,2), -I/2]])

lib/python3.12/site-packages/sympy/physics/tests/test_secondquant.py

@@ -0,0 +1,1280 @@
+from sympy.physics.secondquant import (
+    Dagger, Bd, VarBosonicBasis, BBra, B, BKet, FixedBosonicBasis,
+    matrix_rep, apply_operators, InnerProduct, Commutator, KroneckerDelta,
+    AnnihilateBoson, CreateBoson, BosonicOperator,
+    F, Fd, FKet, BosonState, CreateFermion, AnnihilateFermion,
+    evaluate_deltas, AntiSymmetricTensor, contraction, NO, wicks,
+    PermutationOperator, simplify_index_permutations,
+    _sort_anticommuting_fermions, _get_ordered_dummies,
+    substitute_dummies, FockStateBosonKet,
+    ContractionAppliesOnlyToFermions
+)
+
+from sympy.concrete.summations import Sum
+from sympy.core.function import (Function, expand)
+from sympy.core.numbers import (I, Rational)
+from sympy.core.singleton import S
+from sympy.core.symbol import (Dummy, Symbol, symbols)
+from sympy.functions.elementary.miscellaneous import sqrt
+from sympy.printing.repr import srepr
+from sympy.simplify.simplify import simplify
+
+from sympy.testing.pytest import slow, raises
+from sympy.printing.latex import latex
+
+
+def test_PermutationOperator():
+    p, q, r, s = symbols('p,q,r,s')
+    f, g, h, i = map(Function, 'fghi')
+    P = PermutationOperator
+    assert P(p, q).get_permuted(f(p)*g(q)) == -f(q)*g(p)
+    assert P(p, q).get_permuted(f(p, q)) == -f(q, p)
+    assert P(p, q).get_permuted(f(p)) == f(p)
+    expr = (f(p)*g(q)*h(r)*i(s)
+        - f(q)*g(p)*h(r)*i(s)
+        - f(p)*g(q)*h(s)*i(r)
+        + f(q)*g(p)*h(s)*i(r))
+    perms = [P(p, q), P(r, s)]
+    assert (simplify_index_permutations(expr, perms) ==
+        P(p, q)*P(r, s)*f(p)*g(q)*h(r)*i(s))
+    assert latex(P(p, q)) == 'P(pq)'
+
+
+def test_index_permutations_with_dummies():
+    a, b, c, d = symbols('a b c d')
+    p, q, r, s = symbols('p q r s', cls=Dummy)
+    f, g = map(Function, 'fg')
+    P = PermutationOperator
+
+    # No dummy substitution necessary
+    expr = f(a, b, p, q) - f(b, a, p, q)
+    assert simplify_index_permutations(
+        expr, [P(a, b)]) == P(a, b)*f(a, b, p, q)
+
+    # Cases where dummy substitution is needed
+    expected = P(a, b)*substitute_dummies(f(a, b, p, q))
+
+    expr = f(a, b, p, q) - f(b, a, q, p)
+    result = simplify_index_permutations(expr, [P(a, b)])
+    assert expected == substitute_dummies(result)
+
+    expr = f(a, b, q, p) - f(b, a, p, q)
+    result = simplify_index_permutations(expr, [P(a, b)])
+    assert expected == substitute_dummies(result)
+
+    # A case where nothing can be done
+    expr = f(a, b, q, p) - g(b, a, p, q)
+    result = simplify_index_permutations(expr, [P(a, b)])
+    assert expr == result
+
+
+def test_dagger():
+    i, j, n, m = symbols('i,j,n,m')
+    assert Dagger(1) == 1
+    assert Dagger(1.0) == 1.0
+    assert Dagger(2*I) == -2*I
+    assert Dagger(S.Half*I/3.0) == I*Rational(-1, 2)/3.0
+    assert Dagger(BKet([n])) == BBra([n])
+    assert Dagger(B(0)) == Bd(0)
+    assert Dagger(Bd(0)) == B(0)
+    assert Dagger(B(n)) == Bd(n)
+    assert Dagger(Bd(n)) == B(n)
+    assert Dagger(B(0) + B(1)) == Bd(0) + Bd(1)
+    assert Dagger(n*m) == Dagger(n)*Dagger(m)  # n, m commute
+    assert Dagger(B(n)*B(m)) == Bd(m)*Bd(n)
+    assert Dagger(B(n)**10) == Dagger(B(n))**10
+    assert Dagger('a') == Dagger(Symbol('a'))
+    assert Dagger(Dagger('a')) == Symbol('a')
+
+
+def test_operator():
+    i, j = symbols('i,j')
+    o = BosonicOperator(i)
+    assert o.state == i
+    assert o.is_symbolic
+    o = BosonicOperator(1)
+    assert o.state == 1
+    assert not o.is_symbolic
+
+
+def test_create():
+    i, j, n, m = symbols('i,j,n,m')
+    o = Bd(i)
+    assert latex(o) == "{b^\\dagger_{i}}"
+    assert isinstance(o, CreateBoson)
+    o = o.subs(i, j)
+    assert o.atoms(Symbol) == {j}
+    o = Bd(0)
+    assert o.apply_operator(BKet([n])) == sqrt(n + 1)*BKet([n + 1])
+    o = Bd(n)
+    assert o.apply_operator(BKet([n])) == o*BKet([n])
+
+
+def test_annihilate():
+    i, j, n, m = symbols('i,j,n,m')
+    o = B(i)
+    assert latex(o) == "b_{i}"
+    assert isinstance(o, AnnihilateBoson)
+    o = o.subs(i, j)
+    assert o.atoms(Symbol) == {j}
+    o = B(0)
+    assert o.apply_operator(BKet([n])) == sqrt(n)*BKet([n - 1])
+    o = B(n)
+    assert o.apply_operator(BKet([n])) == o*BKet([n])
+
+
+def test_basic_state():
+    i, j, n, m = symbols('i,j,n,m')
+    s = BosonState([0, 1, 2, 3, 4])
+    assert len(s) == 5
+    assert s.args[0] == tuple(range(5))
+    assert s.up(0) == BosonState([1, 1, 2, 3, 4])
+    assert s.down(4) == BosonState([0, 1, 2, 3, 3])
+    for i in range(5):
+        assert s.up(i).down(i) == s
+    assert s.down(0) == 0
+    for i in range(5):
+        assert s[i] == i
+    s = BosonState([n, m])
+    assert s.down(0) == BosonState([n - 1, m])
+    assert s.up(0) == BosonState([n + 1, m])
+
+
+def test_basic_apply():
+    n = symbols("n")
+    e = B(0)*BKet([n])
+    assert apply_operators(e) == sqrt(n)*BKet([n - 1])
+    e = Bd(0)*BKet([n])
+    assert apply_operators(e) == sqrt(n + 1)*BKet([n + 1])
+
+
+def test_complex_apply():
+    n, m = symbols("n,m")
+    o = Bd(0)*B(0)*Bd(1)*B(0)
+    e = apply_operators(o*BKet([n, m]))
+    answer = sqrt(n)*sqrt(m + 1)*(-1 + n)*BKet([-1 + n, 1 + m])
+    assert expand(e) == expand(answer)
+
+
+def test_number_operator():
+    n = symbols("n")
+    o = Bd(0)*B(0)
+    e = apply_operators(o*BKet([n]))
+    assert e == n*BKet([n])
+
+
+def test_inner_product():
+    i, j, k, l = symbols('i,j,k,l')
+    s1 = BBra([0])
+    s2 = BKet([1])
+    assert InnerProduct(s1, Dagger(s1)) == 1
+    assert InnerProduct(s1, s2) == 0
+    s1 = BBra([i, j])
+    s2 = BKet([k, l])
+    r = InnerProduct(s1, s2)
+    assert r == KroneckerDelta(i, k)*KroneckerDelta(j, l)
+
+
+def test_symbolic_matrix_elements():
+    n, m = symbols('n,m')
+    s1 = BBra([n])
+    s2 = BKet([m])
+    o = B(0)
+    e = apply_operators(s1*o*s2)
+    assert e == sqrt(m)*KroneckerDelta(n, m - 1)
+
+
+def test_matrix_elements():
+    b = VarBosonicBasis(5)
+    o = B(0)
+    m = matrix_rep(o, b)
+    for i in range(4):
+        assert m[i, i + 1] == sqrt(i + 1)
+    o = Bd(0)
+    m = matrix_rep(o, b)
+    for i in range(4):
+        assert m[i + 1, i] == sqrt(i + 1)
+
+
+def test_fixed_bosonic_basis():
+    b = FixedBosonicBasis(2, 2)
+    # assert b == [FockState((2, 0)), FockState((1, 1)), FockState((0, 2))]
+    state = b.state(1)
+    assert state == FockStateBosonKet((1, 1))
+    assert b.index(state) == 1
+    assert b.state(1) == b[1]
+    assert len(b) == 3
+    assert str(b) == '[FockState((2, 0)), FockState((1, 1)), FockState((0, 2))]'
+    assert repr(b) == '[FockState((2, 0)), FockState((1, 1)), FockState((0, 2))]'
+    assert srepr(b) == '[FockState((2, 0)), FockState((1, 1)), FockState((0, 2))]'
+
+
+@slow
+def test_sho():
+    n, m = symbols('n,m')
+    h_n = Bd(n)*B(n)*(n + S.Half)
+    H = Sum(h_n, (n, 0, 5))
+    o = H.doit(deep=False)
+    b = FixedBosonicBasis(2, 6)
+    m = matrix_rep(o, b)
+    # We need to double check these energy values to make sure that they
+    # are correct and have the proper degeneracies!
+    diag = [1, 2, 3, 3, 4, 5, 4, 5, 6, 7, 5, 6, 7, 8, 9, 6, 7, 8, 9, 10, 11]
+    for i in range(len(diag)):
+        assert diag[i] == m[i, i]
+
+
+def test_commutation():
+    n, m = symbols("n,m", above_fermi=True)
+    c = Commutator(B(0), Bd(0))
+    assert c == 1
+    c = Commutator(Bd(0), B(0))
+    assert c == -1
+    c = Commutator(B(n), Bd(0))
+    assert c == KroneckerDelta(n, 0)
+    c = Commutator(B(0), B(0))
+    assert c == 0
+    c = Commutator(B(0), Bd(0))
+    e = simplify(apply_operators(c*BKet([n])))
+    assert e == BKet([n])
+    c = Commutator(B(0), B(1))
+    e = simplify(apply_operators(c*BKet([n, m])))
+    assert e == 0
+
+    c = Commutator(F(m), Fd(m))
+    assert c == +1 - 2*NO(Fd(m)*F(m))
+    c = Commutator(Fd(m), F(m))
+    assert c.expand() == -1 + 2*NO(Fd(m)*F(m))
+
+    C = Commutator
+    X, Y, Z = symbols('X,Y,Z', commutative=False)
+    assert C(C(X, Y), Z) != 0
+    assert C(C(X, Z), Y) != 0
+    assert C(Y, C(X, Z)) != 0
+
+    i, j, k, l = symbols('i,j,k,l', below_fermi=True)
+    a, b, c, d = symbols('a,b,c,d', above_fermi=True)
+    p, q, r, s = symbols('p,q,r,s')
+    D = KroneckerDelta
+
+    assert C(Fd(a), F(i)) == -2*NO(F(i)*Fd(a))
+    assert C(Fd(j), NO(Fd(a)*F(i))).doit(wicks=True) == -D(j, i)*Fd(a)
+    assert C(Fd(a)*F(i), Fd(b)*F(j)).doit(wicks=True) == 0
+
+    c1 = Commutator(F(a), Fd(a))
+    assert Commutator.eval(c1, c1) == 0
+    c = Commutator(Fd(a)*F(i),Fd(b)*F(j))
+    assert latex(c) == r'\left[{a^\dagger_{a}} a_{i},{a^\dagger_{b}} a_{j}\right]'
+    assert repr(c) == 'Commutator(CreateFermion(a)*AnnihilateFermion(i),CreateFermion(b)*AnnihilateFermion(j))'
+    assert str(c) == '[CreateFermion(a)*AnnihilateFermion(i),CreateFermion(b)*AnnihilateFermion(j)]'
+
+
+def test_create_f():
+    i, j, n, m = symbols('i,j,n,m')
+    o = Fd(i)
+    assert isinstance(o, CreateFermion)
+    o = o.subs(i, j)
+    assert o.atoms(Symbol) == {j}
+    o = Fd(1)
+    assert o.apply_operator(FKet([n])) == FKet([1, n])
+    assert o.apply_operator(FKet([n])) == -FKet([n, 1])
+    o = Fd(n)
+    assert o.apply_operator(FKet([])) == FKet([n])
+
+    vacuum = FKet([], fermi_level=4)
+    assert vacuum == FKet([], fermi_level=4)
+
+    i, j, k, l = symbols('i,j,k,l', below_fermi=True)
+    a, b, c, d = symbols('a,b,c,d', above_fermi=True)
+    p, q, r, s = symbols('p,q,r,s')
+
+    assert Fd(i).apply_operator(FKet([i, j, k], 4)) == FKet([j, k], 4)
+    assert Fd(a).apply_operator(FKet([i, b, k], 4)) == FKet([a, i, b, k], 4)
+
+    assert Dagger(B(p)).apply_operator(q) == q*CreateBoson(p)
+    assert repr(Fd(p)) == 'CreateFermion(p)'
+    assert srepr(Fd(p)) == "CreateFermion(Symbol('p'))"
+    assert latex(Fd(p)) == r'{a^\dagger_{p}}'
+
+
+def test_annihilate_f():
+    i, j, n, m = symbols('i,j,n,m')
+    o = F(i)
+    assert isinstance(o, AnnihilateFermion)
+    o = o.subs(i, j)
+    assert o.atoms(Symbol) == {j}
+    o = F(1)
+    assert o.apply_operator(FKet([1, n])) == FKet([n])
+    assert o.apply_operator(FKet([n, 1])) == -FKet([n])
+    o = F(n)
+    assert o.apply_operator(FKet([n])) == FKet([])
+
+    i, j, k, l = symbols('i,j,k,l', below_fermi=True)
+    a, b, c, d = symbols('a,b,c,d', above_fermi=True)
+    p, q, r, s = symbols('p,q,r,s')
+    assert F(i).apply_operator(FKet([i, j, k], 4)) == 0
+    assert F(a).apply_operator(FKet([i, b, k], 4)) == 0
+    assert F(l).apply_operator(FKet([i, j, k], 3)) == 0
+    assert F(l).apply_operator(FKet([i, j, k], 4)) == FKet([l, i, j, k], 4)
+    assert str(F(p)) == 'f(p)'
+    assert repr(F(p)) == 'AnnihilateFermion(p)'
+    assert srepr(F(p)) == "AnnihilateFermion(Symbol('p'))"
+    assert latex(F(p)) == 'a_{p}'
+
+
+def test_create_b():
+    i, j, n, m = symbols('i,j,n,m')
+    o = Bd(i)
+    assert isinstance(o, CreateBoson)
+    o = o.subs(i, j)
+    assert o.atoms(Symbol) == {j}
+    o = Bd(0)
+    assert o.apply_operator(BKet([n])) == sqrt(n + 1)*BKet([n + 1])
+    o = Bd(n)
+    assert o.apply_operator(BKet([n])) == o*BKet([n])
+
+
+def test_annihilate_b():
+    i, j, n, m = symbols('i,j,n,m')
+    o = B(i)
+    assert isinstance(o, AnnihilateBoson)
+    o = o.subs(i, j)
+    assert o.atoms(Symbol) == {j}
+    o = B(0)
+
+
+def test_wicks():
+    p, q, r, s = symbols('p,q,r,s', above_fermi=True)
+
+    # Testing for particles only
+
+    str = F(p)*Fd(q)
+    assert wicks(str) == NO(F(p)*Fd(q)) + KroneckerDelta(p, q)
+    str = Fd(p)*F(q)
+    assert wicks(str) == NO(Fd(p)*F(q))
+
+    str = F(p)*Fd(q)*F(r)*Fd(s)
+    nstr = wicks(str)
+    fasit = NO(
+        KroneckerDelta(p, q)*KroneckerDelta(r, s)
+        + KroneckerDelta(p, q)*AnnihilateFermion(r)*CreateFermion(s)
+        + KroneckerDelta(r, s)*AnnihilateFermion(p)*CreateFermion(q)
+        - KroneckerDelta(p, s)*AnnihilateFermion(r)*CreateFermion(q)
+        - AnnihilateFermion(p)*AnnihilateFermion(r)*CreateFermion(q)*CreateFermion(s))
+    assert nstr == fasit
+
+    assert (p*q*nstr).expand() == wicks(p*q*str)
+    assert (nstr*p*q*2).expand() == wicks(str*p*q*2)
+
+    # Testing CC equations particles and holes
+    i, j, k, l = symbols('i j k l', below_fermi=True, cls=Dummy)
+    a, b, c, d = symbols('a b c d', above_fermi=True, cls=Dummy)
+    p, q, r, s = symbols('p q r s', cls=Dummy)
+
+    assert (wicks(F(a)*NO(F(i)*F(j))*Fd(b)) ==
+            NO(F(a)*F(i)*F(j)*Fd(b)) +
+            KroneckerDelta(a, b)*NO(F(i)*F(j)))
+    assert (wicks(F(a)*NO(F(i)*F(j)*F(k))*Fd(b)) ==
+            NO(F(a)*F(i)*F(j)*F(k)*Fd(b)) -
+            KroneckerDelta(a, b)*NO(F(i)*F(j)*F(k)))
+
+    expr = wicks(Fd(i)*NO(Fd(j)*F(k))*F(l))
+    assert (expr ==
+           -KroneckerDelta(i, k)*NO(Fd(j)*F(l)) -
+            KroneckerDelta(j, l)*NO(Fd(i)*F(k)) -
+            KroneckerDelta(i, k)*KroneckerDelta(j, l) +
+            KroneckerDelta(i, l)*NO(Fd(j)*F(k)) +
+            NO(Fd(i)*Fd(j)*F(k)*F(l)))
+    expr = wicks(F(a)*NO(F(b)*Fd(c))*Fd(d))
+    assert (expr ==
+           -KroneckerDelta(a, c)*NO(F(b)*Fd(d)) -
+            KroneckerDelta(b, d)*NO(F(a)*Fd(c)) -
+            KroneckerDelta(a, c)*KroneckerDelta(b, d) +
+            KroneckerDelta(a, d)*NO(F(b)*Fd(c)) +
+            NO(F(a)*F(b)*Fd(c)*Fd(d)))
+
+
+def test_NO():
+    i, j, k, l = symbols('i j k l', below_fermi=True)
+    a, b, c, d = symbols('a b c d', above_fermi=True)
+    p, q, r, s = symbols('p q r s', cls=Dummy)
+
+    assert (NO(Fd(p)*F(q) + Fd(a)*F(b)) ==
+       NO(Fd(p)*F(q)) + NO(Fd(a)*F(b)))
+    assert (NO(Fd(i)*NO(F(j)*Fd(a))) ==
+       NO(Fd(i)*F(j)*Fd(a)))
+    assert NO(1) == 1
+    assert NO(i) == i
+    assert (NO(Fd(a)*Fd(b)*(F(c) + F(d))) ==
+            NO(Fd(a)*Fd(b)*F(c)) +
+            NO(Fd(a)*Fd(b)*F(d)))
+
+    assert NO(Fd(a)*F(b))._remove_brackets() == Fd(a)*F(b)
+    assert NO(F(j)*Fd(i))._remove_brackets() == F(j)*Fd(i)
+
+    assert (NO(Fd(p)*F(q)).subs(Fd(p), Fd(a) + Fd(i)) ==
+            NO(Fd(a)*F(q)) + NO(Fd(i)*F(q)))
+    assert (NO(Fd(p)*F(q)).subs(F(q), F(a) + F(i)) ==
+            NO(Fd(p)*F(a)) + NO(Fd(p)*F(i)))
+
+    expr = NO(Fd(p)*F(q))._remove_brackets()
+    assert wicks(expr) == NO(expr)
+
+    assert NO(Fd(a)*F(b)) == - NO(F(b)*Fd(a))
+
+    no = NO(Fd(a)*F(i)*F(b)*Fd(j))
+    l1 = list(no.iter_q_creators())
+    assert l1 == [0, 1]
+    l2 = list(no.iter_q_annihilators())
+    assert l2 == [3, 2]
+    no = NO(Fd(a)*Fd(i))
+    assert no.has_q_creators == 1
+    assert no.has_q_annihilators == -1
+    assert str(no) == ':CreateFermion(a)*CreateFermion(i):'
+    assert repr(no) == 'NO(CreateFermion(a)*CreateFermion(i))'
+    assert latex(no) == r'\left\{{a^\dagger_{a}} {a^\dagger_{i}}\right\}'
+    raises(NotImplementedError, lambda:  NO(Bd(p)*F(q)))
+
+
+def test_sorting():
+    i, j = symbols('i,j', below_fermi=True)
+    a, b = symbols('a,b', above_fermi=True)
+    p, q = symbols('p,q')
+
+    # p, q
+    assert _sort_anticommuting_fermions([Fd(p), F(q)]) == ([Fd(p), F(q)], 0)
+    assert _sort_anticommuting_fermions([F(p), Fd(q)]) == ([Fd(q), F(p)], 1)
+
+    # i, p
+    assert _sort_anticommuting_fermions([F(p), Fd(i)]) == ([F(p), Fd(i)], 0)
+    assert _sort_anticommuting_fermions([Fd(i), F(p)]) == ([F(p), Fd(i)], 1)
+    assert _sort_anticommuting_fermions([Fd(p), Fd(i)]) == ([Fd(p), Fd(i)], 0)
+    assert _sort_anticommuting_fermions([Fd(i), Fd(p)]) == ([Fd(p), Fd(i)], 1)
+    assert _sort_anticommuting_fermions([F(p), F(i)]) == ([F(i), F(p)], 1)
+    assert _sort_anticommuting_fermions([F(i), F(p)]) == ([F(i), F(p)], 0)
+    assert _sort_anticommuting_fermions([Fd(p), F(i)]) == ([F(i), Fd(p)], 1)
+    assert _sort_anticommuting_fermions([F(i), Fd(p)]) == ([F(i), Fd(p)], 0)
+
+    # a, p
+    assert _sort_anticommuting_fermions([F(p), Fd(a)]) == ([Fd(a), F(p)], 1)
+    assert _sort_anticommuting_fermions([Fd(a), F(p)]) == ([Fd(a), F(p)], 0)
+    assert _sort_anticommuting_fermions([Fd(p), Fd(a)]) == ([Fd(a), Fd(p)], 1)
+    assert _sort_anticommuting_fermions([Fd(a), Fd(p)]) == ([Fd(a), Fd(p)], 0)
+    assert _sort_anticommuting_fermions([F(p), F(a)]) == ([F(p), F(a)], 0)
+    assert _sort_anticommuting_fermions([F(a), F(p)]) == ([F(p), F(a)], 1)
+    assert _sort_anticommuting_fermions([Fd(p), F(a)]) == ([Fd(p), F(a)], 0)
+    assert _sort_anticommuting_fermions([F(a), Fd(p)]) == ([Fd(p), F(a)], 1)
+
+    # i, a
+    assert _sort_anticommuting_fermions([F(i), Fd(j)]) == ([F(i), Fd(j)], 0)
+    assert _sort_anticommuting_fermions([Fd(j), F(i)]) == ([F(i), Fd(j)], 1)
+    assert _sort_anticommuting_fermions([Fd(a), Fd(i)]) == ([Fd(a), Fd(i)], 0)
+    assert _sort_anticommuting_fermions([Fd(i), Fd(a)]) == ([Fd(a), Fd(i)], 1)
+    assert _sort_anticommuting_fermions([F(a), F(i)]) == ([F(i), F(a)], 1)
+    assert _sort_anticommuting_fermions([F(i), F(a)]) == ([F(i), F(a)], 0)
+
+
+def test_contraction():
+    i, j, k, l = symbols('i,j,k,l', below_fermi=True)
+    a, b, c, d = symbols('a,b,c,d', above_fermi=True)
+    p, q, r, s = symbols('p,q,r,s')
+    assert contraction(Fd(i), F(j)) == KroneckerDelta(i, j)
+    assert contraction(F(a), Fd(b)) == KroneckerDelta(a, b)
+    assert contraction(F(a), Fd(i)) == 0
+    assert contraction(Fd(a), F(i)) == 0
+    assert contraction(F(i), Fd(a)) == 0
+    assert contraction(Fd(i), F(a)) == 0
+    assert contraction(Fd(i), F(p)) == KroneckerDelta(i, p)
+    restr = evaluate_deltas(contraction(Fd(p), F(q)))
+    assert restr.is_only_below_fermi
+    restr = evaluate_deltas(contraction(F(p), Fd(q)))
+    assert restr.is_only_above_fermi
+    raises(ContractionAppliesOnlyToFermions, lambda: contraction(B(a), Fd(b)))
+
+
+def test_evaluate_deltas():
+    i, j, k = symbols('i,j,k')
+
+    r = KroneckerDelta(i, j) * KroneckerDelta(j, k)
+    assert evaluate_deltas(r) == KroneckerDelta(i, k)
+
+    r = KroneckerDelta(i, 0) * KroneckerDelta(j, k)
+    assert evaluate_deltas(r) == KroneckerDelta(i, 0) * KroneckerDelta(j, k)
+
+    r = KroneckerDelta(1, j) * KroneckerDelta(j, k)
+    assert evaluate_deltas(r) == KroneckerDelta(1, k)
+
+    r = KroneckerDelta(j, 2) * KroneckerDelta(k, j)
+    assert evaluate_deltas(r) == KroneckerDelta(2, k)
+
+    r = KroneckerDelta(i, 0) * KroneckerDelta(i, j) * KroneckerDelta(j, 1)
+    assert evaluate_deltas(r) == 0
+
+    r = (KroneckerDelta(0, i) * KroneckerDelta(0, j)
+         * KroneckerDelta(1, j) * KroneckerDelta(1, j))
+    assert evaluate_deltas(r) == 0
+
+
+def test_Tensors():
+    i, j, k, l = symbols('i j k l', below_fermi=True, cls=Dummy)
+    a, b, c, d = symbols('a b c d', above_fermi=True, cls=Dummy)
+    p, q, r, s = symbols('p q r s')
+
+    AT = AntiSymmetricTensor
+    assert AT('t', (a, b), (i, j)) == -AT('t', (b, a), (i, j))
+    assert AT('t', (a, b), (i, j)) == AT('t', (b, a), (j, i))
+    assert AT('t', (a, b), (i, j)) == -AT('t', (a, b), (j, i))
+    assert AT('t', (a, a), (i, j)) == 0
+    assert AT('t', (a, b), (i, i)) == 0
+    assert AT('t', (a, b, c), (i, j)) == -AT('t', (b, a, c), (i, j))
+    assert AT('t', (a, b, c), (i, j, k)) == AT('t', (b, a, c), (i, k, j))
+
+    tabij = AT('t', (a, b), (i, j))
+    assert tabij.has(a)
+    assert tabij.has(b)
+    assert tabij.has(i)
+    assert tabij.has(j)
+    assert tabij.subs(b, c) == AT('t', (a, c), (i, j))
+    assert (2*tabij).subs(i, c) == 2*AT('t', (a, b), (c, j))
+    assert tabij.symbol == Symbol('t')
+    assert latex(tabij) == '{t^{ab}_{ij}}'
+    assert str(tabij) == 't((_a, _b),(_i, _j))'
+
+    assert AT('t', (a, a), (i, j)).subs(a, b) == AT('t', (b, b), (i, j))
+    assert AT('t', (a, i), (a, j)).subs(a, b) == AT('t', (b, i), (b, j))
+
+
+def test_fully_contracted():
+    i, j, k, l = symbols('i j k l', below_fermi=True)
+    a, b, c, d = symbols('a b c d', above_fermi=True)
+    p, q, r, s = symbols('p q r s', cls=Dummy)
+
+    Fock = (AntiSymmetricTensor('f', (p,), (q,))*
+            NO(Fd(p)*F(q)))
+    V = (AntiSymmetricTensor('v', (p, q), (r, s))*
+         NO(Fd(p)*Fd(q)*F(s)*F(r)))/4
+
+    Fai = wicks(NO(Fd(i)*F(a))*Fock,
+            keep_only_fully_contracted=True,
+            simplify_kronecker_deltas=True)
+    assert Fai == AntiSymmetricTensor('f', (a,), (i,))
+    Vabij = wicks(NO(Fd(i)*Fd(j)*F(b)*F(a))*V,
+            keep_only_fully_contracted=True,
+            simplify_kronecker_deltas=True)
+    assert Vabij == AntiSymmetricTensor('v', (a, b), (i, j))
+
+
+def test_substitute_dummies_without_dummies():
+    i, j = symbols('i,j')
+    assert substitute_dummies(att(i, j) + 2) == att(i, j) + 2
+    assert substitute_dummies(att(i, j) + 1) == att(i, j) + 1
+
+
+def test_substitute_dummies_NO_operator():
+    i, j = symbols('i j', cls=Dummy)
+    assert substitute_dummies(att(i, j)*NO(Fd(i)*F(j))
+                - att(j, i)*NO(Fd(j)*F(i))) == 0
+
+
+def test_substitute_dummies_SQ_operator():
+    i, j = symbols('i j', cls=Dummy)
+    assert substitute_dummies(att(i, j)*Fd(i)*F(j)
+                - att(j, i)*Fd(j)*F(i)) == 0
+
+
+def test_substitute_dummies_new_indices():
+    i, j = symbols('i j', below_fermi=True, cls=Dummy)
+    a, b = symbols('a b', above_fermi=True, cls=Dummy)
+    p, q = symbols('p q', cls=Dummy)
+    f = Function('f')
+    assert substitute_dummies(f(i, a, p) - f(j, b, q), new_indices=True) == 0
+
+
+def test_substitute_dummies_substitution_order():
+    i, j, k, l = symbols('i j k l', below_fermi=True, cls=Dummy)
+    f = Function('f')
+    from sympy.utilities.iterables import variations
+    for permut in variations([i, j, k, l], 4):
+        assert substitute_dummies(f(*permut) - f(i, j, k, l)) == 0
+
+
+def test_dummy_order_inner_outer_lines_VT1T1T1():
+    ii = symbols('i', below_fermi=True)
+    aa = symbols('a', above_fermi=True)
+    k, l = symbols('k l', below_fermi=True, cls=Dummy)
+    c, d = symbols('c d', above_fermi=True, cls=Dummy)
+
+    v = Function('v')
+    t = Function('t')
+    dums = _get_ordered_dummies
+
+    # Coupled-Cluster T1 terms with V*T1*T1*T1
+    # t^{a}_{k} t^{c}_{i} t^{d}_{l} v^{lk}_{dc}
+    exprs = [
+        # permut v and t <=> swapping internal lines, equivalent
+        # irrespective of symmetries in v
+        v(k, l, c, d)*t(c, ii)*t(d, l)*t(aa, k),
+        v(l, k, c, d)*t(c, ii)*t(d, k)*t(aa, l),
+        v(k, l, d, c)*t(d, ii)*t(c, l)*t(aa, k),
+        v(l, k, d, c)*t(d, ii)*t(c, k)*t(aa, l),
+    ]
+    for permut in exprs[1:]:
+        assert dums(exprs[0]) != dums(permut)
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+
+
+def test_dummy_order_inner_outer_lines_VT1T1T1T1():
+    ii, jj = symbols('i j', below_fermi=True)
+    aa, bb = symbols('a b', above_fermi=True)
+    k, l = symbols('k l', below_fermi=True, cls=Dummy)
+    c, d = symbols('c d', above_fermi=True, cls=Dummy)
+
+    v = Function('v')
+    t = Function('t')
+    dums = _get_ordered_dummies
+
+    # Coupled-Cluster T2 terms with V*T1*T1*T1*T1
+    exprs = [
+        # permut t <=> swapping external lines, not equivalent
+        # except if v has certain symmetries.
+        v(k, l, c, d)*t(c, ii)*t(d, jj)*t(aa, k)*t(bb, l),
+        v(k, l, c, d)*t(c, jj)*t(d, ii)*t(aa, k)*t(bb, l),
+        v(k, l, c, d)*t(c, ii)*t(d, jj)*t(bb, k)*t(aa, l),
+        v(k, l, c, d)*t(c, jj)*t(d, ii)*t(bb, k)*t(aa, l),
+    ]
+    for permut in exprs[1:]:
+        assert dums(exprs[0]) != dums(permut)
+        assert substitute_dummies(exprs[0]) != substitute_dummies(permut)
+    exprs = [
+        # permut v <=> swapping external lines, not equivalent
+        # except if v has certain symmetries.
+        #
+        # Note that in contrast to above, these permutations have identical
+        # dummy order.  That is because the proximity to external indices
+        # has higher influence on the canonical dummy ordering than the
+        # position of a dummy on the factors.  In fact, the terms here are
+        # similar in structure as the result of the dummy substitutions above.
+        v(k, l, c, d)*t(c, ii)*t(d, jj)*t(aa, k)*t(bb, l),
+        v(l, k, c, d)*t(c, ii)*t(d, jj)*t(aa, k)*t(bb, l),
+        v(k, l, d, c)*t(c, ii)*t(d, jj)*t(aa, k)*t(bb, l),
+        v(l, k, d, c)*t(c, ii)*t(d, jj)*t(aa, k)*t(bb, l),
+    ]
+    for permut in exprs[1:]:
+        assert dums(exprs[0]) == dums(permut)
+        assert substitute_dummies(exprs[0]) != substitute_dummies(permut)
+    exprs = [
+        # permut t and v <=> swapping internal lines, equivalent.
+        # Canonical dummy order is different, and a consistent
+        # substitution reveals the equivalence.
+        v(k, l, c, d)*t(c, ii)*t(d, jj)*t(aa, k)*t(bb, l),
+        v(k, l, d, c)*t(c, jj)*t(d, ii)*t(aa, k)*t(bb, l),
+        v(l, k, c, d)*t(c, ii)*t(d, jj)*t(bb, k)*t(aa, l),
+        v(l, k, d, c)*t(c, jj)*t(d, ii)*t(bb, k)*t(aa, l),
+    ]
+    for permut in exprs[1:]:
+        assert dums(exprs[0]) != dums(permut)
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+
+
+def test_get_subNO():
+    p, q, r = symbols('p,q,r')
+    assert NO(F(p)*F(q)*F(r)).get_subNO(1) == NO(F(p)*F(r))
+    assert NO(F(p)*F(q)*F(r)).get_subNO(0) == NO(F(q)*F(r))
+    assert NO(F(p)*F(q)*F(r)).get_subNO(2) == NO(F(p)*F(q))
+
+
+def test_equivalent_internal_lines_VT1T1():
+    i, j, k, l = symbols('i j k l', below_fermi=True, cls=Dummy)
+    a, b, c, d = symbols('a b c d', above_fermi=True, cls=Dummy)
+
+    v = Function('v')
+    t = Function('t')
+    dums = _get_ordered_dummies
+
+    exprs = [  # permute v.  Different dummy order. Not equivalent.
+        v(i, j, a, b)*t(a, i)*t(b, j),
+        v(j, i, a, b)*t(a, i)*t(b, j),
+        v(i, j, b, a)*t(a, i)*t(b, j),
+    ]
+    for permut in exprs[1:]:
+        assert dums(exprs[0]) != dums(permut)
+        assert substitute_dummies(exprs[0]) != substitute_dummies(permut)
+
+    exprs = [  # permute v.  Different dummy order. Equivalent
+        v(i, j, a, b)*t(a, i)*t(b, j),
+        v(j, i, b, a)*t(a, i)*t(b, j),
+    ]
+    for permut in exprs[1:]:
+        assert dums(exprs[0]) != dums(permut)
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+
+    exprs = [  # permute t.  Same dummy order, not equivalent.
+        v(i, j, a, b)*t(a, i)*t(b, j),
+        v(i, j, a, b)*t(b, i)*t(a, j),
+    ]
+    for permut in exprs[1:]:
+        assert dums(exprs[0]) == dums(permut)
+        assert substitute_dummies(exprs[0]) != substitute_dummies(permut)
+
+    exprs = [  # permute v and t.  Different dummy order, equivalent
+        v(i, j, a, b)*t(a, i)*t(b, j),
+        v(j, i, a, b)*t(a, j)*t(b, i),
+        v(i, j, b, a)*t(b, i)*t(a, j),
+        v(j, i, b, a)*t(b, j)*t(a, i),
+    ]
+    for permut in exprs[1:]:
+        assert dums(exprs[0]) != dums(permut)
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+
+
+def test_equivalent_internal_lines_VT2conjT2():
+    # this diagram requires special handling in TCE
+    i, j, k, l, m, n = symbols('i j k l m n', below_fermi=True, cls=Dummy)
+    a, b, c, d, e, f = symbols('a b c d e f', above_fermi=True, cls=Dummy)
+    p1, p2, p3, p4 = symbols('p1 p2 p3 p4', above_fermi=True, cls=Dummy)
+    h1, h2, h3, h4 = symbols('h1 h2 h3 h4', below_fermi=True, cls=Dummy)
+
+    from sympy.utilities.iterables import variations
+
+    v = Function('v')
+    t = Function('t')
+    dums = _get_ordered_dummies
+
+    # v(abcd)t(abij)t(ijcd)
+    template = v(p1, p2, p3, p4)*t(p1, p2, i, j)*t(i, j, p3, p4)
+    permutator = variations([a, b, c, d], 4)
+    base = template.subs(zip([p1, p2, p3, p4], next(permutator)))
+    for permut in permutator:
+        subslist = zip([p1, p2, p3, p4], permut)
+        expr = template.subs(subslist)
+        assert dums(base) != dums(expr)
+        assert substitute_dummies(expr) == substitute_dummies(base)
+    template = v(p1, p2, p3, p4)*t(p1, p2, j, i)*t(j, i, p3, p4)
+    permutator = variations([a, b, c, d], 4)
+    base = template.subs(zip([p1, p2, p3, p4], next(permutator)))
+    for permut in permutator:
+        subslist = zip([p1, p2, p3, p4], permut)
+        expr = template.subs(subslist)
+        assert dums(base) != dums(expr)
+        assert substitute_dummies(expr) == substitute_dummies(base)
+
+    # v(abcd)t(abij)t(jicd)
+    template = v(p1, p2, p3, p4)*t(p1, p2, i, j)*t(j, i, p3, p4)
+    permutator = variations([a, b, c, d], 4)
+    base = template.subs(zip([p1, p2, p3, p4], next(permutator)))
+    for permut in permutator:
+        subslist = zip([p1, p2, p3, p4], permut)
+        expr = template.subs(subslist)
+        assert dums(base) != dums(expr)
+        assert substitute_dummies(expr) == substitute_dummies(base)
+    template = v(p1, p2, p3, p4)*t(p1, p2, j, i)*t(i, j, p3, p4)
+    permutator = variations([a, b, c, d], 4)
+    base = template.subs(zip([p1, p2, p3, p4], next(permutator)))
+    for permut in permutator:
+        subslist = zip([p1, p2, p3, p4], permut)
+        expr = template.subs(subslist)
+        assert dums(base) != dums(expr)
+        assert substitute_dummies(expr) == substitute_dummies(base)
+
+
+def test_equivalent_internal_lines_VT2conjT2_ambiguous_order():
+    # These diagrams invokes _determine_ambiguous() because the
+    # dummies can not be ordered unambiguously by the key alone
+    i, j, k, l, m, n = symbols('i j k l m n', below_fermi=True, cls=Dummy)
+    a, b, c, d, e, f = symbols('a b c d e f', above_fermi=True, cls=Dummy)
+    p1, p2, p3, p4 = symbols('p1 p2 p3 p4', above_fermi=True, cls=Dummy)
+    h1, h2, h3, h4 = symbols('h1 h2 h3 h4', below_fermi=True, cls=Dummy)
+
+    from sympy.utilities.iterables import variations
+
+    v = Function('v')
+    t = Function('t')
+    dums = _get_ordered_dummies
+
+    # v(abcd)t(abij)t(cdij)
+    template = v(p1, p2, p3, p4)*t(p1, p2, i, j)*t(p3, p4, i, j)
+    permutator = variations([a, b, c, d], 4)
+    base = template.subs(zip([p1, p2, p3, p4], next(permutator)))
+    for permut in permutator:
+        subslist = zip([p1, p2, p3, p4], permut)
+        expr = template.subs(subslist)
+        assert dums(base) != dums(expr)
+        assert substitute_dummies(expr) == substitute_dummies(base)
+    template = v(p1, p2, p3, p4)*t(p1, p2, j, i)*t(p3, p4, i, j)
+    permutator = variations([a, b, c, d], 4)
+    base = template.subs(zip([p1, p2, p3, p4], next(permutator)))
+    for permut in permutator:
+        subslist = zip([p1, p2, p3, p4], permut)
+        expr = template.subs(subslist)
+        assert dums(base) != dums(expr)
+        assert substitute_dummies(expr) == substitute_dummies(base)
+
+
+def test_equivalent_internal_lines_VT2():
+    i, j, k, l = symbols('i j k l', below_fermi=True, cls=Dummy)
+    a, b, c, d = symbols('a b c d', above_fermi=True, cls=Dummy)
+
+    v = Function('v')
+    t = Function('t')
+    dums = _get_ordered_dummies
+    exprs = [
+        # permute v. Same dummy order, not equivalent.
+        #
+        # This test show that the dummy order may not be sensitive to all
+        # index permutations.  The following expressions have identical
+        # structure as the resulting terms from of the dummy substitutions
+        # in the test above.  Here, all expressions have the same dummy
+        # order, so they cannot be simplified by means of dummy
+        # substitution.  In order to simplify further, it is necessary to
+        # exploit symmetries in the objects, for instance if t or v is
+        # antisymmetric.
+        v(i, j, a, b)*t(a, b, i, j),
+        v(j, i, a, b)*t(a, b, i, j),
+        v(i, j, b, a)*t(a, b, i, j),
+        v(j, i, b, a)*t(a, b, i, j),
+    ]
+    for permut in exprs[1:]:
+        assert dums(exprs[0]) == dums(permut)
+        assert substitute_dummies(exprs[0]) != substitute_dummies(permut)
+
+    exprs = [
+        # permute t.
+        v(i, j, a, b)*t(a, b, i, j),
+        v(i, j, a, b)*t(b, a, i, j),
+        v(i, j, a, b)*t(a, b, j, i),
+        v(i, j, a, b)*t(b, a, j, i),
+    ]
+    for permut in exprs[1:]:
+        assert dums(exprs[0]) != dums(permut)
+        assert substitute_dummies(exprs[0]) != substitute_dummies(permut)
+
+    exprs = [  # permute v and t.  Relabelling of dummies should be equivalent.
+        v(i, j, a, b)*t(a, b, i, j),
+        v(j, i, a, b)*t(a, b, j, i),
+        v(i, j, b, a)*t(b, a, i, j),
+        v(j, i, b, a)*t(b, a, j, i),
+    ]
+    for permut in exprs[1:]:
+        assert dums(exprs[0]) != dums(permut)
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+
+
+def test_internal_external_VT2T2():
+    ii, jj = symbols('i j', below_fermi=True)
+    aa, bb = symbols('a b', above_fermi=True)
+    k, l = symbols('k l', below_fermi=True, cls=Dummy)
+    c, d = symbols('c d', above_fermi=True, cls=Dummy)
+
+    v = Function('v')
+    t = Function('t')
+    dums = _get_ordered_dummies
+
+    exprs = [
+        v(k, l, c, d)*t(aa, c, ii, k)*t(bb, d, jj, l),
+        v(l, k, c, d)*t(aa, c, ii, l)*t(bb, d, jj, k),
+        v(k, l, d, c)*t(aa, d, ii, k)*t(bb, c, jj, l),
+        v(l, k, d, c)*t(aa, d, ii, l)*t(bb, c, jj, k),
+    ]
+    for permut in exprs[1:]:
+        assert dums(exprs[0]) != dums(permut)
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+    exprs = [
+        v(k, l, c, d)*t(aa, c, ii, k)*t(d, bb, jj, l),
+        v(l, k, c, d)*t(aa, c, ii, l)*t(d, bb, jj, k),
+        v(k, l, d, c)*t(aa, d, ii, k)*t(c, bb, jj, l),
+        v(l, k, d, c)*t(aa, d, ii, l)*t(c, bb, jj, k),
+    ]
+    for permut in exprs[1:]:
+        assert dums(exprs[0]) != dums(permut)
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+    exprs = [
+        v(k, l, c, d)*t(c, aa, ii, k)*t(bb, d, jj, l),
+        v(l, k, c, d)*t(c, aa, ii, l)*t(bb, d, jj, k),
+        v(k, l, d, c)*t(d, aa, ii, k)*t(bb, c, jj, l),
+        v(l, k, d, c)*t(d, aa, ii, l)*t(bb, c, jj, k),
+    ]
+    for permut in exprs[1:]:
+        assert dums(exprs[0]) != dums(permut)
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+
+
+def test_internal_external_pqrs():
+    ii, jj = symbols('i j')
+    aa, bb = symbols('a b')
+    k, l = symbols('k l', cls=Dummy)
+    c, d = symbols('c d', cls=Dummy)
+
+    v = Function('v')
+    t = Function('t')
+    dums = _get_ordered_dummies
+
+    exprs = [
+        v(k, l, c, d)*t(aa, c, ii, k)*t(bb, d, jj, l),
+        v(l, k, c, d)*t(aa, c, ii, l)*t(bb, d, jj, k),
+        v(k, l, d, c)*t(aa, d, ii, k)*t(bb, c, jj, l),
+        v(l, k, d, c)*t(aa, d, ii, l)*t(bb, c, jj, k),
+    ]
+    for permut in exprs[1:]:
+        assert dums(exprs[0]) != dums(permut)
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+
+
+def test_dummy_order_well_defined():
+    aa, bb = symbols('a b', above_fermi=True)
+    k, l, m = symbols('k l m', below_fermi=True, cls=Dummy)
+    c, d = symbols('c d', above_fermi=True, cls=Dummy)
+    p, q = symbols('p q', cls=Dummy)
+
+    A = Function('A')
+    B = Function('B')
+    C = Function('C')
+    dums = _get_ordered_dummies
+
+    # We go through all key components in the order of increasing priority,
+    # and consider only fully orderable expressions.  Non-orderable expressions
+    # are tested elsewhere.
+
+    # pos in first factor determines sort order
+    assert dums(A(k, l)*B(l, k)) == [k, l]
+    assert dums(A(l, k)*B(l, k)) == [l, k]
+    assert dums(A(k, l)*B(k, l)) == [k, l]
+    assert dums(A(l, k)*B(k, l)) == [l, k]
+
+    # factors involving the index
+    assert dums(A(k, l)*B(l, m)*C(k, m)) == [l, k, m]
+    assert dums(A(k, l)*B(l, m)*C(m, k)) == [l, k, m]
+    assert dums(A(l, k)*B(l, m)*C(k, m)) == [l, k, m]
+    assert dums(A(l, k)*B(l, m)*C(m, k)) == [l, k, m]
+    assert dums(A(k, l)*B(m, l)*C(k, m)) == [l, k, m]
+    assert dums(A(k, l)*B(m, l)*C(m, k)) == [l, k, m]
+    assert dums(A(l, k)*B(m, l)*C(k, m)) == [l, k, m]
+    assert dums(A(l, k)*B(m, l)*C(m, k)) == [l, k, m]
+
+    # same, but with factor order determined by non-dummies
+    assert dums(A(k, aa, l)*A(l, bb, m)*A(bb, k, m)) == [l, k, m]
+    assert dums(A(k, aa, l)*A(l, bb, m)*A(bb, m, k)) == [l, k, m]
+    assert dums(A(k, aa, l)*A(m, bb, l)*A(bb, k, m)) == [l, k, m]
+    assert dums(A(k, aa, l)*A(m, bb, l)*A(bb, m, k)) == [l, k, m]
+    assert dums(A(l, aa, k)*A(l, bb, m)*A(bb, k, m)) == [l, k, m]
+    assert dums(A(l, aa, k)*A(l, bb, m)*A(bb, m, k)) == [l, k, m]
+    assert dums(A(l, aa, k)*A(m, bb, l)*A(bb, k, m)) == [l, k, m]
+    assert dums(A(l, aa, k)*A(m, bb, l)*A(bb, m, k)) == [l, k, m]
+
+    # index range
+    assert dums(A(p, c, k)*B(p, c, k)) == [k, c, p]
+    assert dums(A(p, k, c)*B(p, c, k)) == [k, c, p]
+    assert dums(A(c, k, p)*B(p, c, k)) == [k, c, p]
+    assert dums(A(c, p, k)*B(p, c, k)) == [k, c, p]
+    assert dums(A(k, c, p)*B(p, c, k)) == [k, c, p]
+    assert dums(A(k, p, c)*B(p, c, k)) == [k, c, p]
+    assert dums(B(p, c, k)*A(p, c, k)) == [k, c, p]
+    assert dums(B(p, k, c)*A(p, c, k)) == [k, c, p]
+    assert dums(B(c, k, p)*A(p, c, k)) == [k, c, p]
+    assert dums(B(c, p, k)*A(p, c, k)) == [k, c, p]
+    assert dums(B(k, c, p)*A(p, c, k)) == [k, c, p]
+    assert dums(B(k, p, c)*A(p, c, k)) == [k, c, p]
+
+
+def test_dummy_order_ambiguous():
+    aa, bb = symbols('a b', above_fermi=True)
+    i, j, k, l, m = symbols('i j k l m', below_fermi=True, cls=Dummy)
+    a, b, c, d, e = symbols('a b c d e', above_fermi=True, cls=Dummy)
+    p, q = symbols('p q', cls=Dummy)
+    p1, p2, p3, p4 = symbols('p1 p2 p3 p4', above_fermi=True, cls=Dummy)
+    p5, p6, p7, p8 = symbols('p5 p6 p7 p8', above_fermi=True, cls=Dummy)
+    h1, h2, h3, h4 = symbols('h1 h2 h3 h4', below_fermi=True, cls=Dummy)
+    h5, h6, h7, h8 = symbols('h5 h6 h7 h8', below_fermi=True, cls=Dummy)
+
+    A = Function('A')
+    B = Function('B')
+
+    from sympy.utilities.iterables import variations
+
+    # A*A*A*A*B  --  ordering of p5 and p4 is used to figure out the rest
+    template = A(p1, p2)*A(p4, p1)*A(p2, p3)*A(p3, p5)*B(p5, p4)
+    permutator = variations([a, b, c, d, e], 5)
+    base = template.subs(zip([p1, p2, p3, p4, p5], next(permutator)))
+    for permut in permutator:
+        subslist = zip([p1, p2, p3, p4, p5], permut)
+        expr = template.subs(subslist)
+        assert substitute_dummies(expr) == substitute_dummies(base)
+
+    # A*A*A*A*A  --  an arbitrary index is assigned and the rest are figured out
+    template = A(p1, p2)*A(p4, p1)*A(p2, p3)*A(p3, p5)*A(p5, p4)
+    permutator = variations([a, b, c, d, e], 5)
+    base = template.subs(zip([p1, p2, p3, p4, p5], next(permutator)))
+    for permut in permutator:
+        subslist = zip([p1, p2, p3, p4, p5], permut)
+        expr = template.subs(subslist)
+        assert substitute_dummies(expr) == substitute_dummies(base)
+
+    # A*A*A  --  ordering of p5 and p4 is used to figure out the rest
+    template = A(p1, p2, p4, p1)*A(p2, p3, p3, p5)*A(p5, p4)
+    permutator = variations([a, b, c, d, e], 5)
+    base = template.subs(zip([p1, p2, p3, p4, p5], next(permutator)))
+    for permut in permutator:
+        subslist = zip([p1, p2, p3, p4, p5], permut)
+        expr = template.subs(subslist)
+        assert substitute_dummies(expr) == substitute_dummies(base)
+
+
+def atv(*args):
+    return AntiSymmetricTensor('v', args[:2], args[2:] )
+
+
+def att(*args):
+    if len(args) == 4:
+        return AntiSymmetricTensor('t', args[:2], args[2:] )
+    elif len(args) == 2:
+        return AntiSymmetricTensor('t', (args[0],), (args[1],))
+
+
+def test_dummy_order_inner_outer_lines_VT1T1T1_AT():
+    ii = symbols('i', below_fermi=True)
+    aa = symbols('a', above_fermi=True)
+    k, l = symbols('k l', below_fermi=True, cls=Dummy)
+    c, d = symbols('c d', above_fermi=True, cls=Dummy)
+
+    # Coupled-Cluster T1 terms with V*T1*T1*T1
+    # t^{a}_{k} t^{c}_{i} t^{d}_{l} v^{lk}_{dc}
+    exprs = [
+        # permut v and t <=> swapping internal lines, equivalent
+        # irrespective of symmetries in v
+        atv(k, l, c, d)*att(c, ii)*att(d, l)*att(aa, k),
+        atv(l, k, c, d)*att(c, ii)*att(d, k)*att(aa, l),
+        atv(k, l, d, c)*att(d, ii)*att(c, l)*att(aa, k),
+        atv(l, k, d, c)*att(d, ii)*att(c, k)*att(aa, l),
+    ]
+    for permut in exprs[1:]:
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+
+
+def test_dummy_order_inner_outer_lines_VT1T1T1T1_AT():
+    ii, jj = symbols('i j', below_fermi=True)
+    aa, bb = symbols('a b', above_fermi=True)
+    k, l = symbols('k l', below_fermi=True, cls=Dummy)
+    c, d = symbols('c d', above_fermi=True, cls=Dummy)
+
+    # Coupled-Cluster T2 terms with V*T1*T1*T1*T1
+    # non-equivalent substitutions (change of sign)
+    exprs = [
+        # permut t <=> swapping external lines
+        atv(k, l, c, d)*att(c, ii)*att(d, jj)*att(aa, k)*att(bb, l),
+        atv(k, l, c, d)*att(c, jj)*att(d, ii)*att(aa, k)*att(bb, l),
+        atv(k, l, c, d)*att(c, ii)*att(d, jj)*att(bb, k)*att(aa, l),
+    ]
+    for permut in exprs[1:]:
+        assert substitute_dummies(exprs[0]) == -substitute_dummies(permut)
+
+    # equivalent substitutions
+    exprs = [
+        atv(k, l, c, d)*att(c, ii)*att(d, jj)*att(aa, k)*att(bb, l),
+        # permut t <=> swapping external lines
+        atv(k, l, c, d)*att(c, jj)*att(d, ii)*att(bb, k)*att(aa, l),
+    ]
+    for permut in exprs[1:]:
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+
+
+def test_equivalent_internal_lines_VT1T1_AT():
+    i, j, k, l = symbols('i j k l', below_fermi=True, cls=Dummy)
+    a, b, c, d = symbols('a b c d', above_fermi=True, cls=Dummy)
+
+    exprs = [  # permute v.  Different dummy order. Not equivalent.
+        atv(i, j, a, b)*att(a, i)*att(b, j),
+        atv(j, i, a, b)*att(a, i)*att(b, j),
+        atv(i, j, b, a)*att(a, i)*att(b, j),
+    ]
+    for permut in exprs[1:]:
+        assert substitute_dummies(exprs[0]) != substitute_dummies(permut)
+
+    exprs = [  # permute v.  Different dummy order. Equivalent
+        atv(i, j, a, b)*att(a, i)*att(b, j),
+        atv(j, i, b, a)*att(a, i)*att(b, j),
+    ]
+    for permut in exprs[1:]:
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+
+    exprs = [  # permute t.  Same dummy order, not equivalent.
+        atv(i, j, a, b)*att(a, i)*att(b, j),
+        atv(i, j, a, b)*att(b, i)*att(a, j),
+    ]
+    for permut in exprs[1:]:
+        assert substitute_dummies(exprs[0]) != substitute_dummies(permut)
+
+    exprs = [  # permute v and t.  Different dummy order, equivalent
+        atv(i, j, a, b)*att(a, i)*att(b, j),
+        atv(j, i, a, b)*att(a, j)*att(b, i),
+        atv(i, j, b, a)*att(b, i)*att(a, j),
+        atv(j, i, b, a)*att(b, j)*att(a, i),
+    ]
+    for permut in exprs[1:]:
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+
+
+def test_equivalent_internal_lines_VT2conjT2_AT():
+    # this diagram requires special handling in TCE
+    i, j, k, l, m, n = symbols('i j k l m n', below_fermi=True, cls=Dummy)
+    a, b, c, d, e, f = symbols('a b c d e f', above_fermi=True, cls=Dummy)
+    p1, p2, p3, p4 = symbols('p1 p2 p3 p4', above_fermi=True, cls=Dummy)
+    h1, h2, h3, h4 = symbols('h1 h2 h3 h4', below_fermi=True, cls=Dummy)
+
+    from sympy.utilities.iterables import variations
+
+    # atv(abcd)att(abij)att(ijcd)
+    template = atv(p1, p2, p3, p4)*att(p1, p2, i, j)*att(i, j, p3, p4)
+    permutator = variations([a, b, c, d], 4)
+    base = template.subs(zip([p1, p2, p3, p4], next(permutator)))
+    for permut in permutator:
+        subslist = zip([p1, p2, p3, p4], permut)
+        expr = template.subs(subslist)
+        assert substitute_dummies(expr) == substitute_dummies(base)
+    template = atv(p1, p2, p3, p4)*att(p1, p2, j, i)*att(j, i, p3, p4)
+    permutator = variations([a, b, c, d], 4)
+    base = template.subs(zip([p1, p2, p3, p4], next(permutator)))
+    for permut in permutator:
+        subslist = zip([p1, p2, p3, p4], permut)
+        expr = template.subs(subslist)
+        assert substitute_dummies(expr) == substitute_dummies(base)
+
+    # atv(abcd)att(abij)att(jicd)
+    template = atv(p1, p2, p3, p4)*att(p1, p2, i, j)*att(j, i, p3, p4)
+    permutator = variations([a, b, c, d], 4)
+    base = template.subs(zip([p1, p2, p3, p4], next(permutator)))
+    for permut in permutator:
+        subslist = zip([p1, p2, p3, p4], permut)
+        expr = template.subs(subslist)
+        assert substitute_dummies(expr) == substitute_dummies(base)
+    template = atv(p1, p2, p3, p4)*att(p1, p2, j, i)*att(i, j, p3, p4)
+    permutator = variations([a, b, c, d], 4)
+    base = template.subs(zip([p1, p2, p3, p4], next(permutator)))
+    for permut in permutator:
+        subslist = zip([p1, p2, p3, p4], permut)
+        expr = template.subs(subslist)
+        assert substitute_dummies(expr) == substitute_dummies(base)
+
+
+def test_equivalent_internal_lines_VT2conjT2_ambiguous_order_AT():
+    # These diagrams invokes _determine_ambiguous() because the
+    # dummies can not be ordered unambiguously by the key alone
+    i, j, k, l, m, n = symbols('i j k l m n', below_fermi=True, cls=Dummy)
+    a, b, c, d, e, f = symbols('a b c d e f', above_fermi=True, cls=Dummy)
+    p1, p2, p3, p4 = symbols('p1 p2 p3 p4', above_fermi=True, cls=Dummy)
+    h1, h2, h3, h4 = symbols('h1 h2 h3 h4', below_fermi=True, cls=Dummy)
+
+    from sympy.utilities.iterables import variations
+
+    # atv(abcd)att(abij)att(cdij)
+    template = atv(p1, p2, p3, p4)*att(p1, p2, i, j)*att(p3, p4, i, j)
+    permutator = variations([a, b, c, d], 4)
+    base = template.subs(zip([p1, p2, p3, p4], next(permutator)))
+    for permut in permutator:
+        subslist = zip([p1, p2, p3, p4], permut)
+        expr = template.subs(subslist)
+        assert substitute_dummies(expr) == substitute_dummies(base)
+    template = atv(p1, p2, p3, p4)*att(p1, p2, j, i)*att(p3, p4, i, j)
+    permutator = variations([a, b, c, d], 4)
+    base = template.subs(zip([p1, p2, p3, p4], next(permutator)))
+    for permut in permutator:
+        subslist = zip([p1, p2, p3, p4], permut)
+        expr = template.subs(subslist)
+        assert substitute_dummies(expr) == substitute_dummies(base)
+
+
+def test_equivalent_internal_lines_VT2_AT():
+    i, j, k, l = symbols('i j k l', below_fermi=True, cls=Dummy)
+    a, b, c, d = symbols('a b c d', above_fermi=True, cls=Dummy)
+
+    exprs = [
+        # permute v. Same dummy order, not equivalent.
+        atv(i, j, a, b)*att(a, b, i, j),
+        atv(j, i, a, b)*att(a, b, i, j),
+        atv(i, j, b, a)*att(a, b, i, j),
+    ]
+    for permut in exprs[1:]:
+        assert substitute_dummies(exprs[0]) != substitute_dummies(permut)
+
+    exprs = [
+        # permute t.
+        atv(i, j, a, b)*att(a, b, i, j),
+        atv(i, j, a, b)*att(b, a, i, j),
+        atv(i, j, a, b)*att(a, b, j, i),
+    ]
+    for permut in exprs[1:]:
+        assert substitute_dummies(exprs[0]) != substitute_dummies(permut)
+
+    exprs = [  # permute v and t.  Relabelling of dummies should be equivalent.
+        atv(i, j, a, b)*att(a, b, i, j),
+        atv(j, i, a, b)*att(a, b, j, i),
+        atv(i, j, b, a)*att(b, a, i, j),
+        atv(j, i, b, a)*att(b, a, j, i),
+    ]
+    for permut in exprs[1:]:
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+
+
+def test_internal_external_VT2T2_AT():
+    ii, jj = symbols('i j', below_fermi=True)
+    aa, bb = symbols('a b', above_fermi=True)
+    k, l = symbols('k l', below_fermi=True, cls=Dummy)
+    c, d = symbols('c d', above_fermi=True, cls=Dummy)
+
+    exprs = [
+        atv(k, l, c, d)*att(aa, c, ii, k)*att(bb, d, jj, l),
+        atv(l, k, c, d)*att(aa, c, ii, l)*att(bb, d, jj, k),
+        atv(k, l, d, c)*att(aa, d, ii, k)*att(bb, c, jj, l),
+        atv(l, k, d, c)*att(aa, d, ii, l)*att(bb, c, jj, k),
+    ]
+    for permut in exprs[1:]:
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+    exprs = [
+        atv(k, l, c, d)*att(aa, c, ii, k)*att(d, bb, jj, l),
+        atv(l, k, c, d)*att(aa, c, ii, l)*att(d, bb, jj, k),
+        atv(k, l, d, c)*att(aa, d, ii, k)*att(c, bb, jj, l),
+        atv(l, k, d, c)*att(aa, d, ii, l)*att(c, bb, jj, k),
+    ]
+    for permut in exprs[1:]:
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+    exprs = [
+        atv(k, l, c, d)*att(c, aa, ii, k)*att(bb, d, jj, l),
+        atv(l, k, c, d)*att(c, aa, ii, l)*att(bb, d, jj, k),
+        atv(k, l, d, c)*att(d, aa, ii, k)*att(bb, c, jj, l),
+        atv(l, k, d, c)*att(d, aa, ii, l)*att(bb, c, jj, k),
+    ]
+    for permut in exprs[1:]:
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+
+
+def test_internal_external_pqrs_AT():
+    ii, jj = symbols('i j')
+    aa, bb = symbols('a b')
+    k, l = symbols('k l', cls=Dummy)
+    c, d = symbols('c d', cls=Dummy)
+
+    exprs = [
+        atv(k, l, c, d)*att(aa, c, ii, k)*att(bb, d, jj, l),
+        atv(l, k, c, d)*att(aa, c, ii, l)*att(bb, d, jj, k),
+        atv(k, l, d, c)*att(aa, d, ii, k)*att(bb, c, jj, l),
+        atv(l, k, d, c)*att(aa, d, ii, l)*att(bb, c, jj, k),
+    ]
+    for permut in exprs[1:]:
+        assert substitute_dummies(exprs[0]) == substitute_dummies(permut)
+
+
+def test_issue_19661():
+    a = Symbol('0')
+    assert latex(Commutator(Bd(a)**2, B(a))
+                 ) == '- \\left[b_{0},{b^\\dagger_{0}}^{2}\\right]'
+
+
+def test_canonical_ordering_AntiSymmetricTensor():
+    v = symbols("v")
+
+    c, d = symbols(('c','d'), above_fermi=True,
+                                   cls=Dummy)
+    k, l = symbols(('k','l'), below_fermi=True,
+                                   cls=Dummy)
+
+    # formerly, the left gave either the left or the right
+    assert AntiSymmetricTensor(v, (k, l), (d, c)
+        ) == -AntiSymmetricTensor(v, (l, k), (d, c))

lib/python3.12/site-packages/sympy/physics/tests/test_sho.py

@@ -0,0 +1,21 @@
+from sympy.core import symbols, Rational, Function, diff
+from sympy.physics.sho import R_nl, E_nl
+from sympy.simplify.simplify import simplify
+
+
+def test_sho_R_nl():
+    omega, r = symbols('omega r')
+    l = symbols('l', integer=True)
+    u = Function('u')
+
+    # check that it obeys the Schrodinger equation
+    for n in range(5):
+        schreq = ( -diff(u(r), r, 2)/2 + ((l*(l + 1))/(2*r**2)
+                    + omega**2*r**2/2 - E_nl(n, l, omega))*u(r) )
+        result = schreq.subs(u(r), r*R_nl(n, l, omega/2, r))
+        assert simplify(result.doit()) == 0
+
+
+def test_energy():
+    n, l, hw = symbols('n l hw')
+    assert simplify(E_nl(n, l, hw) - (2*n + l + Rational(3, 2))*hw) == 0

lib/python3.12/site-packages/sympy/physics/units/__init__.py

@@ -0,0 +1,453 @@
+# isort:skip_file
+"""
+Dimensional analysis and unit systems.
+
+This module defines dimension/unit systems and physical quantities. It is
+based on a group-theoretical construction where dimensions are represented as
+vectors (coefficients being the exponents), and units are defined as a dimension
+to which we added a scale.
+
+Quantities are built from a factor and a unit, and are the basic objects that
+one will use when doing computations.
+
+All objects except systems and prefixes can be used in SymPy expressions.
+Note that as part of a CAS, various objects do not combine automatically
+under operations.
+
+Details about the implementation can be found in the documentation, and we
+will not repeat all the explanations we gave there concerning our approach.
+Ideas about future developments can be found on the `Github wiki
+<https://github.com/sympy/sympy/wiki/Unit-systems>`_, and you should consult
+this page if you are willing to help.
+
+Useful functions:
+
+- ``find_unit``: easily lookup pre-defined units.
+- ``convert_to(expr, newunit)``: converts an expression into the same
+    expression expressed in another unit.
+
+"""
+
+from .dimensions import Dimension, DimensionSystem
+from .unitsystem import UnitSystem
+from .util import convert_to
+from .quantities import Quantity
+
+from .definitions.dimension_definitions import (
+    amount_of_substance, acceleration, action, area,
+    capacitance, charge, conductance, current, energy,
+    force, frequency, impedance, inductance, length,
+    luminous_intensity, magnetic_density,
+    magnetic_flux, mass, momentum, power, pressure, temperature, time,
+    velocity, voltage, volume
+)
+
+Unit = Quantity
+
+speed = velocity
+luminosity = luminous_intensity
+magnetic_flux_density = magnetic_density
+amount = amount_of_substance
+
+from .prefixes import (
+    # 10-power based:
+    yotta,
+    zetta,
+    exa,
+    peta,
+    tera,
+    giga,
+    mega,
+    kilo,
+    hecto,
+    deca,
+    deci,
+    centi,
+    milli,
+    micro,
+    nano,
+    pico,
+    femto,
+    atto,
+    zepto,
+    yocto,
+    # 2-power based:
+    kibi,
+    mebi,
+    gibi,
+    tebi,
+    pebi,
+    exbi,
+)
+
+from .definitions import (
+    percent, percents,
+    permille,
+    rad, radian, radians,
+    deg, degree, degrees,
+    sr, steradian, steradians,
+    mil, angular_mil, angular_mils,
+    m, meter, meters,
+    kg, kilogram, kilograms,
+    s, second, seconds,
+    A, ampere, amperes,
+    K, kelvin, kelvins,
+    mol, mole, moles,
+    cd, candela, candelas,
+    g, gram, grams,
+    mg, milligram, milligrams,
+    ug, microgram, micrograms,
+    t, tonne, metric_ton,
+    newton, newtons, N,
+    joule, joules, J,
+    watt, watts, W,
+    pascal, pascals, Pa, pa,
+    hertz, hz, Hz,
+    coulomb, coulombs, C,
+    volt, volts, v, V,
+    ohm, ohms,
+    siemens, S, mho, mhos,
+    farad, farads, F,
+    henry, henrys, H,
+    tesla, teslas, T,
+    weber, webers, Wb, wb,
+    optical_power, dioptre, D,
+    lux, lx,
+    katal, kat,
+    gray, Gy,
+    becquerel, Bq,
+    km, kilometer, kilometers,
+    dm, decimeter, decimeters,
+    cm, centimeter, centimeters,
+    mm, millimeter, millimeters,
+    um, micrometer, micrometers, micron, microns,
+    nm, nanometer, nanometers,
+    pm, picometer, picometers,
+    ft, foot, feet,
+    inch, inches,
+    yd, yard, yards,
+    mi, mile, miles,
+    nmi, nautical_mile, nautical_miles,
+    angstrom, angstroms,
+    ha, hectare,
+    l, L, liter, liters,
+    dl, dL, deciliter, deciliters,
+    cl, cL, centiliter, centiliters,
+    ml, mL, milliliter, milliliters,
+    ms, millisecond, milliseconds,
+    us, microsecond, microseconds,
+    ns, nanosecond, nanoseconds,
+    ps, picosecond, picoseconds,
+    minute, minutes,
+    h, hour, hours,
+    day, days,
+    anomalistic_year, anomalistic_years,
+    sidereal_year, sidereal_years,
+    tropical_year, tropical_years,
+    common_year, common_years,
+    julian_year, julian_years,
+    draconic_year, draconic_years,
+    gaussian_year, gaussian_years,
+    full_moon_cycle, full_moon_cycles,
+    year, years,
+    G, gravitational_constant,
+    c, speed_of_light,
+    elementary_charge,
+    hbar,
+    planck,
+    eV, electronvolt, electronvolts,
+    avogadro_number,
+    avogadro, avogadro_constant,
+    boltzmann, boltzmann_constant,
+    stefan, stefan_boltzmann_constant,
+    R, molar_gas_constant,
+    faraday_constant,
+    josephson_constant,
+    von_klitzing_constant,
+    Da, dalton, amu, amus, atomic_mass_unit, atomic_mass_constant,
+    me, electron_rest_mass,
+    gee, gees, acceleration_due_to_gravity,
+    u0, magnetic_constant, vacuum_permeability,
+    e0, electric_constant, vacuum_permittivity,
+    Z0, vacuum_impedance,
+    coulomb_constant, electric_force_constant,
+    atmosphere, atmospheres, atm,
+    kPa,
+    bar, bars,
+    pound, pounds,
+    psi,
+    dHg0,
+    mmHg, torr,
+    mmu, mmus, milli_mass_unit,
+    quart, quarts,
+    ly, lightyear, lightyears,
+    au, astronomical_unit, astronomical_units,
+    planck_mass,
+    planck_time,
+    planck_temperature,
+    planck_length,
+    planck_charge,
+    planck_area,
+    planck_volume,
+    planck_momentum,
+    planck_energy,
+    planck_force,
+    planck_power,
+    planck_density,
+    planck_energy_density,
+    planck_intensity,
+    planck_angular_frequency,
+    planck_pressure,
+    planck_current,
+    planck_voltage,
+    planck_impedance,
+    planck_acceleration,
+    bit, bits,
+    byte,
+    kibibyte, kibibytes,
+    mebibyte, mebibytes,
+    gibibyte, gibibytes,
+    tebibyte, tebibytes,
+    pebibyte, pebibytes,
+    exbibyte, exbibytes,
+)
+
+from .systems import (
+    mks, mksa, si
+)
+
+
+def find_unit(quantity, unit_system="SI"):
+    """
+    Return a list of matching units or dimension names.
+
+    - If ``quantity`` is a string -- units/dimensions containing the string
+    `quantity`.
+    - If ``quantity`` is a unit or dimension -- units having matching base
+    units or dimensions.
+
+    Examples
+    ========
+
+    >>> from sympy.physics import units as u
+    >>> u.find_unit('charge')
+    ['C', 'coulomb', 'coulombs', 'planck_charge', 'elementary_charge']
+    >>> u.find_unit(u.charge)
+    ['C', 'coulomb', 'coulombs', 'planck_charge', 'elementary_charge']
+    >>> u.find_unit("ampere")
+    ['ampere', 'amperes']
+    >>> u.find_unit('angstrom')
+    ['angstrom', 'angstroms']
+    >>> u.find_unit('volt')
+    ['volt', 'volts', 'electronvolt', 'electronvolts', 'planck_voltage']
+    >>> u.find_unit(u.inch**3)[:9]
+    ['L', 'l', 'cL', 'cl', 'dL', 'dl', 'mL', 'ml', 'liter']
+    """
+    unit_system = UnitSystem.get_unit_system(unit_system)
+
+    import sympy.physics.units as u
+    rv = []
+    if isinstance(quantity, str):
+        rv = [i for i in dir(u) if quantity in i and isinstance(getattr(u, i), Quantity)]
+        dim = getattr(u, quantity)
+        if isinstance(dim, Dimension):
+            rv.extend(find_unit(dim))
+    else:
+        for i in sorted(dir(u)):
+            other = getattr(u, i)
+            if not isinstance(other, Quantity):
+                continue
+            if isinstance(quantity, Quantity):
+                if quantity.dimension == other.dimension:
+                    rv.append(str(i))
+            elif isinstance(quantity, Dimension):
+                if other.dimension == quantity:
+                    rv.append(str(i))
+            elif other.dimension == Dimension(unit_system.get_dimensional_expr(quantity)):
+                rv.append(str(i))
+    return sorted(set(rv), key=lambda x: (len(x), x))
+
+# NOTE: the old units module had additional variables:
+# 'density', 'illuminance', 'resistance'.
+# They were not dimensions, but units (old Unit class).
+
+__all__ = [
+    'Dimension', 'DimensionSystem',
+    'UnitSystem',
+    'convert_to',
+    'Quantity',
+
+    'amount_of_substance', 'acceleration', 'action', 'area',
+    'capacitance', 'charge', 'conductance', 'current', 'energy',
+    'force', 'frequency', 'impedance', 'inductance', 'length',
+    'luminous_intensity', 'magnetic_density',
+    'magnetic_flux', 'mass', 'momentum', 'power', 'pressure', 'temperature', 'time',
+    'velocity', 'voltage', 'volume',
+
+    'Unit',
+
+    'speed',
+    'luminosity',
+    'magnetic_flux_density',
+    'amount',
+
+    'yotta',
+    'zetta',
+    'exa',
+    'peta',
+    'tera',
+    'giga',
+    'mega',
+    'kilo',
+    'hecto',
+    'deca',
+    'deci',
+    'centi',
+    'milli',
+    'micro',
+    'nano',
+    'pico',
+    'femto',
+    'atto',
+    'zepto',
+    'yocto',
+
+    'kibi',
+    'mebi',
+    'gibi',
+    'tebi',
+    'pebi',
+    'exbi',
+
+    'percent', 'percents',
+    'permille',
+    'rad', 'radian', 'radians',
+    'deg', 'degree', 'degrees',
+    'sr', 'steradian', 'steradians',
+    'mil', 'angular_mil', 'angular_mils',
+    'm', 'meter', 'meters',
+    'kg', 'kilogram', 'kilograms',
+    's', 'second', 'seconds',
+    'A', 'ampere', 'amperes',
+    'K', 'kelvin', 'kelvins',
+    'mol', 'mole', 'moles',
+    'cd', 'candela', 'candelas',
+    'g', 'gram', 'grams',
+    'mg', 'milligram', 'milligrams',
+    'ug', 'microgram', 'micrograms',
+    't', 'tonne', 'metric_ton',
+    'newton', 'newtons', 'N',
+    'joule', 'joules', 'J',
+    'watt', 'watts', 'W',
+    'pascal', 'pascals', 'Pa', 'pa',
+    'hertz', 'hz', 'Hz',
+    'coulomb', 'coulombs', 'C',
+    'volt', 'volts', 'v', 'V',
+    'ohm', 'ohms',
+    'siemens', 'S', 'mho', 'mhos',
+    'farad', 'farads', 'F',
+    'henry', 'henrys', 'H',
+    'tesla', 'teslas', 'T',
+    'weber', 'webers', 'Wb', 'wb',
+    'optical_power', 'dioptre', 'D',
+    'lux', 'lx',
+    'katal', 'kat',
+    'gray', 'Gy',
+    'becquerel', 'Bq',
+    'km', 'kilometer', 'kilometers',
+    'dm', 'decimeter', 'decimeters',
+    'cm', 'centimeter', 'centimeters',
+    'mm', 'millimeter', 'millimeters',
+    'um', 'micrometer', 'micrometers', 'micron', 'microns',
+    'nm', 'nanometer', 'nanometers',
+    'pm', 'picometer', 'picometers',
+    'ft', 'foot', 'feet',
+    'inch', 'inches',
+    'yd', 'yard', 'yards',
+    'mi', 'mile', 'miles',
+    'nmi', 'nautical_mile', 'nautical_miles',
+    'angstrom', 'angstroms',
+    'ha', 'hectare',
+    'l', 'L', 'liter', 'liters',
+    'dl', 'dL', 'deciliter', 'deciliters',
+    'cl', 'cL', 'centiliter', 'centiliters',
+    'ml', 'mL', 'milliliter', 'milliliters',
+    'ms', 'millisecond', 'milliseconds',
+    'us', 'microsecond', 'microseconds',
+    'ns', 'nanosecond', 'nanoseconds',
+    'ps', 'picosecond', 'picoseconds',
+    'minute', 'minutes',
+    'h', 'hour', 'hours',
+    'day', 'days',
+    'anomalistic_year', 'anomalistic_years',
+    'sidereal_year', 'sidereal_years',
+    'tropical_year', 'tropical_years',
+    'common_year', 'common_years',
+    'julian_year', 'julian_years',
+    'draconic_year', 'draconic_years',
+    'gaussian_year', 'gaussian_years',
+    'full_moon_cycle', 'full_moon_cycles',
+    'year', 'years',
+    'G', 'gravitational_constant',
+    'c', 'speed_of_light',
+    'elementary_charge',
+    'hbar',
+    'planck',
+    'eV', 'electronvolt', 'electronvolts',
+    'avogadro_number',
+    'avogadro', 'avogadro_constant',
+    'boltzmann', 'boltzmann_constant',
+    'stefan', 'stefan_boltzmann_constant',
+    'R', 'molar_gas_constant',
+    'faraday_constant',
+    'josephson_constant',
+    'von_klitzing_constant',
+    'Da', 'dalton', 'amu', 'amus', 'atomic_mass_unit', 'atomic_mass_constant',
+    'me', 'electron_rest_mass',
+    'gee', 'gees', 'acceleration_due_to_gravity',
+    'u0', 'magnetic_constant', 'vacuum_permeability',
+    'e0', 'electric_constant', 'vacuum_permittivity',
+    'Z0', 'vacuum_impedance',
+    'coulomb_constant', 'electric_force_constant',
+    'atmosphere', 'atmospheres', 'atm',
+    'kPa',
+    'bar', 'bars',
+    'pound', 'pounds',
+    'psi',
+    'dHg0',
+    'mmHg', 'torr',
+    'mmu', 'mmus', 'milli_mass_unit',
+    'quart', 'quarts',
+    'ly', 'lightyear', 'lightyears',
+    'au', 'astronomical_unit', 'astronomical_units',
+    'planck_mass',
+    'planck_time',
+    'planck_temperature',
+    'planck_length',
+    'planck_charge',
+    'planck_area',
+    'planck_volume',
+    'planck_momentum',
+    'planck_energy',
+    'planck_force',
+    'planck_power',
+    'planck_density',
+    'planck_energy_density',
+    'planck_intensity',
+    'planck_angular_frequency',
+    'planck_pressure',
+    'planck_current',
+    'planck_voltage',
+    'planck_impedance',
+    'planck_acceleration',
+    'bit', 'bits',
+    'byte',
+    'kibibyte', 'kibibytes',
+    'mebibyte', 'mebibytes',
+    'gibibyte', 'gibibytes',
+    'tebibyte', 'tebibytes',
+    'pebibyte', 'pebibytes',
+    'exbibyte', 'exbibytes',
+
+    'mks', 'mksa', 'si',
+]