`scipy.signal._signaltools:unique_roots`

source: /scipy/signal/_signaltools.py :3029

Signature

def unique_roots ( p , tol = 0.001 , rtype = min )

Summary

Determine unique roots and their multiplicities from a list of roots.

Parameters

p : array_like

The list of roots.

tol : float, optional

The tolerance for two roots to be considered equal in terms of the distance between them. Default is 1e-3. Refer to Notes about the details on roots grouping.

rtype : {'max', 'maximum', 'min', 'minimum', 'avg', 'mean'}, optional

How to determine the returned root if multiple roots are within tol of each other.

'max', 'maximum': pick the maximum of those roots
'min', 'minimum': pick the minimum of those roots
'avg', 'mean': take the average of those roots

When finding minimum or maximum among complex roots they are compared first by the real part and then by the imaginary part.

Returns

unique : ndarray: The list of unique roots.
multiplicity : ndarray: The multiplicity of each root.

Notes

If we have 3 roots a, b and c, such that a is close to b and b is close to c (distance is less than tol), then it doesn't necessarily mean that a is close to c. It means that roots grouping is not unique. In this function we use "greedy" grouping going through the roots in the order they are given in the input p.

This utility function is not specific to roots but can be used for any sequence of values for which uniqueness and multiplicity has to be determined. For a more general routine, see numpy.unique.

Array API Standard Support

unique_roots has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable SCIPY_ARRAY_API=1 and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported.

====================  ====================  ====================
Library               CPU                   GPU
====================  ====================  ====================
NumPy                 ✅                     n/a                 
CuPy                  n/a                   ✅                   
PyTorch               ⛔                     ⛔                   
JAX                   ⛔                     ⛔                   
Dask                  ⛔                     n/a                 
====================  ====================  ====================

See dev-arrayapi for more information.

Examples

from scipy import signal
vals = [0, 1.3, 1.31, 2.8, 1.25, 2.2, 10.3]
uniq, mult = signal.unique_roots(vals, tol=2e-2, rtype='avg')

✓

Check which roots have multiplicity larger than 1:

uniq[mult > 1]

✗

Aliases

scipy.signal.unique_roots