pydsm.relab.cplxpair

pydsm.relab.cplxpair(x, tol=None, dim=None)

Sorts values into complex pairs a la Matlab.

The function takes a vector or multidimensional array of of complex conjugate pairs or real numbers and rearranges it so that the complex numbers are collected into matched pairs of complex conjugates. The pairs are ordered by increasing real part, with purely real elements placed after all the complex pairs.

In the search for complex conjugate pairs a relative tolerance equal to tol is used for comparison purposes. The default tolerance is 100 times the system floating point accuracy.

If the input vector is a multidimensional array, the rearrangement is done working along the axis specifid by the parameter dim or along the first axis with non-unitary length if dim is not provided.

Parameters:

x : array_like of complex

x is an array of complex values, with the assumption that it contains either real values or complex values in conjugate pairs.

tol: real, optional

relative tolerance for the recognition of pairs. Defaults to 100 times the system floating point accuracy for the specific number type.

dim: integer, optional

The axis to operate upon.

Returns:

y : ndarray

y is an array of complex values, with the same values in x, yet now sorted as complex pairs by increasing real part. Real elements in x are place after the complex pairs, sorted in increasing order.

Raises:

ValueError

‘Complex numbers cannot be paired’ if there are unpaired complex entries in x.

See also

eps

the system floating point accuracy

Examples

>>> a = np.exp(2j*np.pi*np.arange(0, 5)/5)
>>> b1 = cplxpair(a)
>>> b2 = np.asarray([-0.80901699-0.58778525j, -0.80901699+0.58778525j,
...                   0.30901699-0.95105652j,  0.30901699+0.95105652j,
...                   1.00000000+0.j])
>>> np.allclose(b1, b2)
True

>>> cplxpair(1)
array([1])

>>> cplxpair([[5, 6, 4], [3, 2, 1]])
array([[3, 2, 1],
       [5, 6, 4]])

>>> cplxpair([[5, 6, 4], [3, 2, 1]], dim=1)
array([[4, 5, 6],
       [1, 2, 3]])