scipy 1.15.3__cp311-cp311-win_amd64.whl → 1.16.0rc2__cp311-cp311-win_amd64.whl

scipy/signal/_ltisys.py

@@ -1354,8 +1354,8 @@ class StateSpace(LinearTimeInvariant):
         )
 
     def _check_binop_other(self, other):
-        return isinstance(other, (StateSpace, np.ndarray, float, complex,
-                                  np.number, int))
+        return isinstance(other, StateSpace | np.ndarray | float | complex |
+                                  np.number | int)
 
     def __mul__(self, other):
         """
@@ -1895,7 +1895,7 @@ def lsim(system, U, T, X0=None, interp=True):
         raise ValueError("Initial time must be nonnegative")
 
     no_input = (U is None or
-                (isinstance(U, (int, float)) and U == 0.) or
+                (isinstance(U, int | float) and U == 0.) or
                 not np.any(U))
 
     if n_steps == 1:
@@ -2260,7 +2260,7 @@ def freqresp(system, w=None, n=10000):
     >>> plt.show()
     """
     if isinstance(system, lti):
-        if isinstance(system, (TransferFunction, ZerosPolesGain)):
+        if isinstance(system, TransferFunction | ZerosPolesGain):
             sys = system
         else:
             sys = system._as_zpk()
@@ -2317,11 +2317,13 @@ def _valid_inputs(A, B, poles, method, rtol, maxiter):
     if A.shape[0] != A.shape[1]:
         raise ValueError("A must be square")
     if len(poles) > A.shape[0]:
-        raise ValueError("maximum number of poles is %d but you asked for %d" %
-                         (A.shape[0], len(poles)))
+        raise ValueError(
+            f"maximum number of poles is {A.shape[0]} but you asked for {len(poles)}"
+        )
     if len(poles) < A.shape[0]:
-        raise ValueError("number of poles is %d but you should provide %d" %
-                         (len(poles), A.shape[0]))
+        raise ValueError(
+            f"number of poles is {len(poles)} but you should provide {A.shape[0]}"
+        )
     r = np.linalg.matrix_rank(B)
     for p in poles:
         if sum(p == poles) > r:
@@ -3032,20 +3034,24 @@ def place_poles(A, B, poles, method="YT", rtol=1e-3, maxiter=30):
 
 
 def dlsim(system, u, t=None, x0=None):
-    """
-    Simulate output of a discrete-time linear system.
+    r"""Simulate output of a discrete-time linear system.
 
     Parameters
     ----------
-    system : tuple of array_like or instance of `dlti`
-        A tuple describing the system.
-        The following gives the number of elements in the tuple and
-        the interpretation:
+    system : dlti | tuple
+        An instance of the LTI class `dlti` or a tuple describing the system.
+        The number of elements in the tuple determine the interpretation. I.e.:
+
+        * ``system``: Instance of LTI class `dlti`. Note that derived instances, such
+          as instances of `TransferFunction`, `ZerosPolesGain`, or `StateSpace`, are
+          allowed as well.
+        * ``(num, den, dt)``: Rational polynomial as described in `TransferFunction`.
+          The coefficients of the polynomials should be specified in descending
+          exponent order,  e.g., z² + 3z + 5 would be represented as ``[1, 3, 5]``.
+        * ``(zeros, poles, gain, dt)``:  Zeros, poles, gain form as described
+          in `ZerosPolesGain`.
+        * ``(A, B, C, D, dt)``: State-space form as described in `StateSpace`.
 
-            * 1: (instance of `dlti`)
-            * 3: (num, den, dt)
-            * 4: (zeros, poles, gain, dt)
-            * 5: (A, B, C, D, dt)
 
     u : array_like
         An input array describing the input at each time `t` (interpolation is
@@ -3148,20 +3154,23 @@ def dlsim(system, u, t=None, x0=None):
 
 
 def dimpulse(system, x0=None, t=None, n=None):
-    """
-    Impulse response of discrete-time system.
+    r"""Impulse response of discrete-time system.
 
     Parameters
     ----------
-    system : tuple of array_like or instance of `dlti`
-        A tuple describing the system.
-        The following gives the number of elements in the tuple and
-        the interpretation:
-
-            * 1: (instance of `dlti`)
-            * 3: (num, den, dt)
-            * 4: (zeros, poles, gain, dt)
-            * 5: (A, B, C, D, dt)
+        system : dlti | tuple
+        An instance of the LTI class `dlti` or a tuple describing the system.
+        The number of elements in the tuple determine the interpretation. I.e.:
+
+        * ``system``: Instance of LTI class `dlti`. Note that derived instances, such
+          as instances of `TransferFunction`, `ZerosPolesGain`, or `StateSpace`, are
+          allowed as well.
+        * ``(num, den, dt)``: Rational polynomial as described in `TransferFunction`.
+          The coefficients of the polynomials should be specified in descending
+          exponent order,  e.g., z² + 3z + 5 would be represented as ``[1, 3, 5]``.
+        * ``(zeros, poles, gain, dt)``:  Zeros, poles, gain form as described
+          in `ZerosPolesGain`.
+        * ``(A, B, C, D, dt)``: State-space form as described in `StateSpace`.
 
     x0 : array_like, optional
         Initial state-vector.  Defaults to zero.
@@ -3187,14 +3196,17 @@ def dimpulse(system, x0=None, t=None, n=None):
     >>> import numpy as np
     >>> from scipy import signal
     >>> import matplotlib.pyplot as plt
-
-    >>> butter = signal.dlti(*signal.butter(3, 0.5))
-    >>> t, y = signal.dimpulse(butter, n=25)
-    >>> plt.step(t, np.squeeze(y))
-    >>> plt.grid()
-    >>> plt.xlabel('n [samples]')
-    >>> plt.ylabel('Amplitude')
-
+    ...
+    >>> dt = 1  # sampling interval is one => time unit is sample number
+    >>> bb, aa = signal.butter(3, 0.25, fs=1/dt)
+    >>> t, y = signal.dimpulse((bb, aa, dt), n=25)
+    ...
+    >>> fig0, ax0 = plt.subplots()
+    >>> ax0.step(t, np.squeeze(y), '.-', where='post')
+    >>> ax0.set_title(r"Impulse Response of a $3^\text{rd}$ Order Butterworth Filter")
+    >>> ax0.set(xlabel='Sample number', ylabel='Amplitude')
+    >>> ax0.grid()
+    >>> plt.show()
     """
     # Convert system to dlti-StateSpace
     if isinstance(system, dlti):
@@ -3235,20 +3247,23 @@ def dimpulse(system, x0=None, t=None, n=None):
 
 
 def dstep(system, x0=None, t=None, n=None):
-    """
-    Step response of discrete-time system.
+    r"""Step response of discrete-time system.
 
     Parameters
     ----------
-    system : tuple of array_like
-        A tuple describing the system.
-        The following gives the number of elements in the tuple and
-        the interpretation:
-
-            * 1: (instance of `dlti`)
-            * 3: (num, den, dt)
-            * 4: (zeros, poles, gain, dt)
-            * 5: (A, B, C, D, dt)
+     system : dlti | tuple
+        An instance of the LTI class `dlti` or a tuple describing the system.
+        The number of elements in the tuple determine the interpretation. I.e.:
+
+        * ``system``: Instance of LTI class `dlti`. Note that derived instances, such
+          as instances of `TransferFunction`, `ZerosPolesGain`, or `StateSpace`, are
+          allowed as well.
+        * ``(num, den, dt)``: Rational polynomial as described in `TransferFunction`.
+          The coefficients of the polynomials should be specified in descending
+          exponent order,  e.g., z² + 3z + 5 would be represented as ``[1, 3, 5]``.
+        * ``(zeros, poles, gain, dt)``:  Zeros, poles, gain form as described
+          in `ZerosPolesGain`.
+        * ``(A, B, C, D, dt)``: State-space form as described in `StateSpace`.
 
     x0 : array_like, optional
         Initial state-vector.  Defaults to zero.
@@ -3271,16 +3286,23 @@ def dstep(system, x0=None, t=None, n=None):
 
     Examples
     --------
+    The following example illustrates how to create a digital Butterworth filer and
+    plot its step response:
+
     >>> import numpy as np
     >>> from scipy import signal
     >>> import matplotlib.pyplot as plt
-
-    >>> butter = signal.dlti(*signal.butter(3, 0.5))
-    >>> t, y = signal.dstep(butter, n=25)
-    >>> plt.step(t, np.squeeze(y))
-    >>> plt.grid()
-    >>> plt.xlabel('n [samples]')
-    >>> plt.ylabel('Amplitude')
+    ...
+    >>> dt = 1  # sampling interval is one => time unit is sample number
+    >>> bb, aa = signal.butter(3, 0.25, fs=1/dt)
+    >>> t, y = signal.dstep((bb, aa, dt), n=25)
+    ...
+    >>> fig0, ax0 = plt.subplots()
+    >>> ax0.step(t, np.squeeze(y), '.-', where='post')
+    >>> ax0.set_title(r"Step Response of a $3^\text{rd}$ Order Butterworth Filter")
+    >>> ax0.set(xlabel='Sample number', ylabel='Amplitude', ylim=(0, 1.1*np.max(y)))
+    >>> ax0.grid()
+    >>> plt.show()
     """
     # Convert system to dlti-StateSpace
     if isinstance(system, dlti):
@@ -3326,14 +3348,19 @@ def dfreqresp(system, w=None, n=10000, whole=False):
 
     Parameters
     ----------
-    system : an instance of the `dlti` class or a tuple describing the system.
-        The following gives the number of elements in the tuple and
-        the interpretation:
-
-            * 1 (instance of `dlti`)
-            * 2 (numerator, denominator, dt)
-            * 3 (zeros, poles, gain, dt)
-            * 4 (A, B, C, D, dt)
+    system : dlti | tuple
+        An instance of the LTI class `dlti` or a tuple describing the system.
+        The number of elements in the tuple determine the interpretation. I.e.:
+
+        * ``system``: Instance of LTI class `dlti`. Note that derived instances, such
+          as instances of `TransferFunction`, `ZerosPolesGain`, or `StateSpace`, are
+          allowed as well.
+        * ``(num, den, dt)``: Rational polynomial as described in `TransferFunction`.
+          The coefficients of the polynomials should be specified in descending
+          exponent order,  e.g., z² + 3z + 5 would be represented as ``[1, 3, 5]``.
+        * ``(zeros, poles, gain, dt)``:  Zeros, poles, gain form as described
+          in `ZerosPolesGain`.
+        * ``(A, B, C, D, dt)``: State-space form as described in `StateSpace`.
 
     w : array_like, optional
         Array of frequencies (in radians/sample). Magnitude and phase data is
@@ -3365,24 +3392,25 @@ def dfreqresp(system, w=None, n=10000, whole=False):
 
     Examples
     --------
-    Generating the Nyquist plot of a transfer function
+    The following example generates the Nyquist plot of the transfer function
+    :math:`H(z) = \frac{1}{z^2 + 2z + 3}`  with a sampling time of 0.05 seconds:
 
     >>> from scipy import signal
     >>> import matplotlib.pyplot as plt
-
-    Construct the transfer function
-    :math:`H(z) = \frac{1}{z^2 + 2z + 3}` with a sampling time of 0.05
-    seconds:
-
-    >>> sys = signal.TransferFunction([1], [1, 2, 3], dt=0.05)
-
+    >>> sys = signal.TransferFunction([1], [1, 2, 3], dt=0.05)  # construct H(z)
     >>> w, H = signal.dfreqresp(sys)
-
-    >>> plt.figure()
-    >>> plt.plot(H.real, H.imag, "b")
-    >>> plt.plot(H.real, -H.imag, "r")
+    ...
+    >>> fig0, ax0 = plt.subplots()
+    >>> ax0.plot(H.real, H.imag, label=r"$H(z=e^{+j\omega})$")
+    >>> ax0.plot(H.real, -H.imag, label=r"$H(z=e^{-j\omega})$")
+    >>> ax0.set_title(r"Nyquist Plot of $H(z) = 1 / (z^2 + 2z + 3)$")
+    >>> ax0.set(xlabel=r"$\text{Re}\{z\}$", ylabel=r"$\text{Im}\{z\}$",
+    ...         xlim=(-0.2, 0.65), aspect='equal')
+    >>> ax0.plot(H[0].real, H[0].imag, 'k.')  # mark H(exp(1j*w[0]))
+    >>> ax0.text(0.2, 0, r"$H(e^{j0})$")
+    >>> ax0.grid(True)
+    >>> ax0.legend()
     >>> plt.show()
-
     """
     if not isinstance(system, dlti):
         if isinstance(system, lti):
@@ -3395,7 +3423,7 @@ def dfreqresp(system, w=None, n=10000, whole=False):
         # No SS->ZPK code exists right now, just SS->TF->ZPK
         system = system._as_tf()
 
-    if not isinstance(system, (TransferFunction, ZerosPolesGain)):
+    if not isinstance(system, TransferFunction | ZerosPolesGain):
         raise ValueError('Unknown system type')
 
     if system.inputs != 1 or system.outputs != 1:
@@ -3421,24 +3449,23 @@ def dfreqresp(system, w=None, n=10000, whole=False):
 
 
 def dbode(system, w=None, n=100):
-    r"""
-    Calculate Bode magnitude and phase data of a discrete-time system.
+    r"""Calculate Bode magnitude and phase data of a discrete-time system.
 
     Parameters
     ----------
-    system :
+    system : dlti | tuple
         An instance of the LTI class `dlti` or a tuple describing the system.
-        The number of elements in the tuple determine the interpretation, i.e.:
-
-        1. ``(sys_dlti)``:  Instance of LTI class `dlti`. Note that derived instances,
-           such as instances of `TransferFunction`, `ZerosPolesGain`, or `StateSpace`,
-           are allowed as well.
-        2. ``(num, den, dt)``: Rational polynomial as described in `TransferFunction`.
-           The coefficients of the polynomials should be specified in descending
-           exponent order,  e.g., z² + 3z + 5 would be represented as ``[1, 3, 5]``.
-        3. ``(zeros, poles, gain, dt)``:  Zeros, poles, gain form as described
-           in `ZerosPolesGain`.
-        4. ``(A, B, C, D, dt)``: State-space form as described in `StateSpace`.
+        The number of elements in the tuple determine the interpretation. I.e.:
+
+        * ``system``: Instance of LTI class `dlti`. Note that derived instances, such
+          as instances of `TransferFunction`, `ZerosPolesGain`, or `StateSpace`, are
+          allowed as well.
+        * ``(num, den, dt)``: Rational polynomial as described in `TransferFunction`.
+          The coefficients of the polynomials should be specified in descending
+          exponent order,  e.g., z² + 3z + 5 would be represented as ``[1, 3, 5]``.
+        * ``(zeros, poles, gain, dt)``:  Zeros, poles, gain form as described
+          in `ZerosPolesGain`.
+        * ``(A, B, C, D, dt)``: State-space form as described in `StateSpace`.
 
     w : array_like, optional
         Array of frequencies normalized to the Nyquist frequency being π, i.e.,

scipy/signal/_polyutils.py

@@ -0,0 +1,172 @@
+"""Partial replacements for numpy polynomial routines, with Array API compatibility.
+
+This module contains both "old-style", np.poly1d, routines from the main numpy
+namespace, and "new-style", np.polynomial.polynomial, routines.
+
+To distinguish the two sets, the "new-style" routine names start with `npp_`
+"""
+import scipy._lib.array_api_extra as xpx
+from scipy._lib._array_api import xp_promote, xp_default_dtype
+
+
+def _sort_cmplx(arr, xp):
+    # xp.sort is undefined for complex dtypes. Here we only need some
+    # consistent way to sort a complex array, including equal magnitude elements.
+    arr = xp.asarray(arr)
+    if xp.isdtype(arr.dtype, 'complex floating'):
+        sorter = abs(arr) + xp.real(arr) + xp.imag(arr)**3
+    else:
+        sorter = arr
+
+    idxs = xp.argsort(sorter)
+    return arr[idxs]
+
+
+def polyroots(coef, *, xp):
+    """numpy.roots, best-effor replacement
+    """
+    if coef.shape[0] < 2:
+        return xp.asarray([], dtype=coef.dtype)
+
+    root_func = getattr(xp, 'roots', None)
+    if root_func:
+        # NB: cupy.roots is broken in CuPy 13.x, but CuPy is handled via delegation
+        # so we never hit this code path with xp being cupy
+        return root_func(coef)
+
+    # companion matrix
+    n = coef.shape[0]
+    a = xp.eye(n - 1, n - 1, k=-1, dtype=coef.dtype)
+    a[:, -1] = -xp.flip(coef[1:]) / coef[0]
+
+    # non-symmetric eigenvalue problem is not in the spec but is available on e.g. torch
+    if hasattr(xp.linalg, 'eigvals'):
+        return xp.linalg.eigvals(a)
+    else:
+        import numpy as np
+        return xp.asarray(np.linalg.eigvals(np.asarray(a)))
+
+
+# https://github.com/numpy/numpy/blob/v2.1.0/numpy/lib/_function_base_impl.py#L1874-L1925
+def _trim_zeros(filt, trim='fb'):
+    first = 0
+    trim = trim.upper()
+    if 'F' in trim:
+        for i in filt:
+            if i != 0.:
+                break
+            else:
+                first = first + 1
+    last = filt.shape[0]
+    if 'B' in trim:
+        for i in filt[::-1]:
+            if i != 0.:
+                break
+            else:
+                last = last - 1
+    return filt[first:last]
+
+
+# ### Old-style routines ###
+
+
+# https://github.com/numpy/numpy/blob/v2.2.0/numpy/lib/_polynomial_impl.py#L1232
+def _poly1d(c_or_r, *, xp):
+    """ Constructor of np.poly1d object from an array of coefficients (r=False)
+    """
+    c_or_r = xpx.atleast_nd(c_or_r, ndim=1, xp=xp)
+    if c_or_r.ndim > 1:
+        raise ValueError("Polynomial must be 1d only.")
+    c_or_r = _trim_zeros(c_or_r, trim='f')
+    if c_or_r.shape[0] == 0:
+        c_or_r = xp.asarray([0], dtype=c_or_r.dtype)
+    return c_or_r
+
+
+# https://github.com/numpy/numpy/blob/v2.2.0/numpy/lib/_polynomial_impl.py#L702-L779
+def polyval(p, x, *, xp):
+    """ Old-style polynomial, `np.polyval`
+    """
+    y = xp.zeros_like(x)
+
+    for pv in p:
+        y = y * x + pv
+    return y
+
+
+# https://github.com/numpy/numpy/blob/v2.2.0/numpy/lib/_polynomial_impl.py#L34-L157
+def poly(seq_of_zeros, *, xp):
+    # Only reproduce the 1D variant of np.poly
+    seq_of_zeros = xp.asarray(seq_of_zeros)
+    seq_of_zeros = xpx.atleast_nd(seq_of_zeros, ndim=1, xp=xp)
+
+    if seq_of_zeros.shape[0] == 0:
+        return 1.0
+
+    # prefer np.convolve etc, if available
+    convolve_func = getattr(xp, 'convolve', None)
+    if convolve_func is None:
+        from scipy.signal import convolve as convolve_func
+
+    dt = seq_of_zeros.dtype
+    a = xp.ones((1,), dtype=dt)
+    one = xp.ones_like(seq_of_zeros[0])
+    for zero in seq_of_zeros:
+        a = convolve_func(a, xp.stack((one, -zero)), mode='full')
+
+    if xp.isdtype(a.dtype, 'complex floating'):
+        # if complex roots are all complex conjugates, the roots are real.
+        roots = xp.asarray(seq_of_zeros, dtype=xp.complex128)
+        if xp.all(_sort_cmplx(roots, xp) == _sort_cmplx(xp.conj(roots), xp)):
+            a = xp.asarray(xp.real(a), copy=True)
+
+    return a
+
+
+# https://github.com/numpy/numpy/blob/v2.2.0/numpy/lib/_polynomial_impl.py#L912
+def polymul(a1, a2, *, xp):
+    a1, a2 = _poly1d(a1, xp=xp), _poly1d(a2, xp=xp)
+
+    # prefer np.convolve etc, if available
+    convolve_func = getattr(xp, 'convolve', None)
+    if convolve_func is None:
+        from scipy.signal import convolve as convolve_func
+
+    val = convolve_func(a1, a2)
+    return val
+
+
+# ### New-style routines ###
+
+
+# https://github.com/numpy/numpy/blob/v2.2.0/numpy/polynomial/polynomial.py#L663
+def npp_polyval(x, c, *, xp, tensor=True):
+    if xp.isdtype(c.dtype, 'integral'):
+        c = xp.astype(c, xp_default_dtype(xp))
+
+    c = xpx.atleast_nd(c, ndim=1, xp=xp)
+    if isinstance(x, tuple | list):
+        x = xp.asarray(x)
+    if tensor:
+        c = xp.reshape(c, (c.shape + (1,)*x.ndim))
+
+    c0, _ = xp_promote(c[-1, ...], x, broadcast=True, xp=xp)
+    for i in range(2, c.shape[0] + 1):
+        c0 = c[-i, ...] + c0*x
+    return c0
+
+
+# https://github.com/numpy/numpy/blob/v2.2.0/numpy/polynomial/polynomial.py#L758-L842
+def npp_polyvalfromroots(x, r, *, xp, tensor=True):
+    r = xpx.atleast_nd(r, ndim=1, xp=xp)
+    # if r.dtype.char in '?bBhHiIlLqQpP':
+    #    r = r.astype(np.double)
+
+    if isinstance(x, tuple | list):
+        x = xp.asarray(x)
+
+    if tensor:
+        r = xp.reshape(r, r.shape + (1,) * x.ndim)
+    elif x.ndim >= r.ndim:
+        raise ValueError("x.ndim must be < r.ndim when tensor == False")
+    return xp.prod(x - r, axis=0)