pmrf.functions.math

Functions

`comb`(N, k[, exact, repetition])	The number of combinations of N things taken k at a time.
`complex2Scalar`(z)	Serialize a list/array of complex numbers.
`complex_2_db`(z)	Return the magnitude in dB of a complex number (as \(20\log_{10}(\|z\|)\)).
`complex_2_db10`(z)	Return the magnitude in dB of a complex number (as \(10\log_{10}(\|z\|)\)).
`complex_2_degree`(z)	Returns the angle complex argument in degrees.
`complex_2_magnitude`(z)	Return the magnitude of the complex argument.
`complex_2_quadrature`(z)	Take a complex number and returns quadrature, which is (length, arc-length from real axis).
`complex_2_radian`(z)	Return the angle complex argument in radian.
`complex_2_reim`(z)	Return real and imaginary parts of a complex number.
`complex_components`(z)	Break up a complex array into all possible scalar components.
`complexify`(f[, name])	Make a function f(scalar) into f(complex).
`conv_cost`(x)
`conv_inter`(x[, axis])	Convolve interleaved signals (e.g. real/imag parts stored sequentially).
`convolve_interleaved`(x[, axis])	Convolve interleaved signals (e.g. real/imag parts stored sequentially).
`cross_ratio`(a, b, c, d)	Calculate the cross ratio of a quadruple of distinct points on the real line.
`dB20`(x)	Convert magnitude to decibels.
`db10_2_mag`(z)	Convert dB (factor 10) to linear magnitude.
`db_2_mag`(x)	Convert decibels to magnitude.
`db_2_magnitude`(z)	Convert dB to linear magnitude.
`db_2_np`(db)	Convert a value in decibel (dB) to neper (Np).
`db_per_100feet_2_db_per_100meter`([...])	Convert attenuation values given in dB/100ft to dB/100m.
`dbdeg_2_reim`(db, deg)	Convert dB magnitude and phase (in deg) arrays into a complex array.
`degree_2_radian`(deg)	Convert angles from degrees to radians.
`dirac_delta`(x)	Calculate Dirac function.
`evaluate_bernstein_basis`(x, coeffs, ...)	Evaluate a polynomial in the Bernstein basis.
`evaluate_power_basis`(x, coeffs, lower_bound, ...)	Evaluate a polynomial in the power basis.
`feet_2_meter`([feet])	Convert length in feet to meter.
`find_closest`(z1, z2, z_approx)	Return z1 or z2 depending on which is closer to z_approx.
`find_correct_sign`(z1, z2, z_approx)	Create new vector from z1, z2 choosing elements with sign matching z_approx.
`inf_to_num`(x)	Convert inf and -inf's to large numbers.
`mag_2_db`(x)	Convert magnitude to decibels.
`mag_2_db10`(z[, zero_nan])	Convert linear magnitude to dB (factor 10).
`magdeg_2_reim`(mag, deg)	Convert linear magnitude and phase (in deg) arrays into a complex array.
`magnitude_2_db`(z[, zero_nan])	Convert linear magnitude to dB.
`meter_2_feet`([meter])	Convert length in meter to feet.
`multiply_by`(x, by[, axis])	Broadcast multiply array x by array by along a specified axis.
`multiply_every`(x, n[, axis])	Multiply blocks of size n along a specified axis.
`neuman`(x)	Calculate Neumans number.
`np_2_db`(x)	Convert a value in Nepers (Np) to decibel (dB).
`nudge_eig`(mat[, cond, min_eig])	Nudge eigenvalues with absolute value smaller than max(cond * max(eigenvalue), min_eig) to that value.
`null`(A[, eps])	Calculate the null space of matrix A.
`polar_2_rect`(radii, angles[, deg])	Convert polar coordinates to rectangular (complex) coordinates.
`radian_2_degree`(rad)	Convert angles from radians to degrees.
`rect_2_polar`(x[, deg])	Convert rectangular (complex) coordinates to polar coordinates.
`rms`(x)	Calculate the Root Mean Square (RMS) of the input.
`round_sig`(x[, sig])	Round to a specific number of significant digits.
`rsolve`(A, B)	Solves x @ A = B.
`scalar2Complex`(s)	Unserialize a list/array of real and imag numbers into a complex array.
`sqrt_known_sign`(z_squared, z_approx)	Return the square root of a complex number, with sign chosen to match z_approx.
`sqrt_phase_unwrap`(z)	Take the square root of a complex number with unwrapped phase.
`sum_every`(x, n[, axis])	Sum blocks of size n along a specified axis.
`unwrap_rad`(phi)	Unwrap a phase given in radians.

pmrf.functions.math.complex_2_magnitude(z)[source]

Return the magnitude of the complex argument.

Parameters:: z (number or array_like) – A complex number or sequence of complex numbers.
Returns:: mag – The absolute value of the input.
Return type:: ndarray or scalar

pmrf.functions.math.complex_2_db(z)[source]

Return the magnitude in dB of a complex number (as \(20\log_{10}(|z|)\)).

The magnitude in dB is defined as \(20\log_{10}(|z|)\) where \(z\) is a complex number.

Parameters:: z (number or array_like) – A complex number or sequence of complex numbers.
Returns:: mag20dB – The magnitude in decibels.
Return type:: ndarray or scalar

pmrf.functions.math.complex_2_db10(z)[source]

Return the magnitude in dB of a complex number (as \(10\log_{10}(|z|)\)).

The magnitude in dB is defined as \(10\log_{10}(|z|)\) where \(z\) is a complex number.

Parameters:: z (number or array_like) – A complex number or sequence of complex numbers.
Returns:: mag10dB – The magnitude in decibels (power factor 10).
Return type:: ndarray or scalar

pmrf.functions.math.complex_2_radian(z)[source]

Return the angle complex argument in radian.

Parameters:: z (number or array_like) – A complex number or sequence of complex numbers.
Returns:: ang_rad – The counterclockwise angle from the positive real axis on the complex plane in the range (-pi, pi], with dtype as numpy.float64.
Return type:: ndarray or scalar

pmrf.functions.math.complex_2_degree(z)[source]

Returns the angle complex argument in degrees.

Parameters:: z (number or array_like) – A complex number or sequence of complex numbers.
Returns:: ang_deg – The angle in degrees.
Return type:: ndarray or scalar

pmrf.functions.math.complex_2_quadrature(z)[source]

Take a complex number and returns quadrature, which is (length, arc-length from real axis).

Arc-length is calculated as \(|z| \arg(z)\).

Parameters:

z (number or array_like) – A complex number or sequence of complex numbers.

Returns:

mag (array like or scalar) – Magnitude (length).
arc_length (array like or scalar) – Arc-length from real axis: angle * magnitude.

pmrf.functions.math.complex_2_reim(z)[source]

Return real and imaginary parts of a complex number.

Parameters:

z (number or array_like) – A complex number or sequence of complex numbers.

Returns:

real (array like or scalar) – Real part of input.
imag (array like or scalar) – Imaginary part of input.

pmrf.functions.math.complex_components(z)[source]

Break up a complex array into all possible scalar components.

Parameters:

z (number or array_like) – A complex number or sequence of complex numbers.

Returns:

c_real (array like or scalar) – Real part.
c_imag (array like or scalar) – Imaginary part.
c_angle (array like or scalar) – Angle in degrees.
c_mag (array like or scalar) – Magnitude.
c_arc (array like or scalar) – Arclength from real axis, angle*magnitude.

pmrf.functions.math.magnitude_2_db(z, zero_nan=True)[source]

Convert linear magnitude to dB.

Parameters:

z (number or array_like) – A complex number or sequence of complex numbers.
zero_nan (bool, optional, default=True) – Replace NaN with zero.

Returns:

z – Magnitude in dB given by \(20 \log_{10}(|z|)\).

Return type:

number or array_like

pmrf.functions.math.mag_2_db10(z, zero_nan=True)[source]

Convert linear magnitude to dB (factor 10).

Parameters:

z (array_like) – A complex number or sequence of complex numbers.
zero_nan (bool, optional, default=True) – Replace NaN with zero.

Returns:

z – Magnitude in dB given by \(10 \log_{10}(|z|)\).

Return type:

array_like

pmrf.functions.math.db_2_magnitude(z)[source]

Convert dB to linear magnitude.

Parameters:: z (number or array_like) – A complex number or sequence of complex numbers.
Returns:: z – 10**((z)/20) where z is a complex number.
Return type:: number or array_like

pmrf.functions.math.db10_2_mag(z)[source]

Convert dB (factor 10) to linear magnitude.

Parameters:: z (array_like) – A complex number or sequence of complex numbers.
Returns:: z – 10**((z)/10) where z is a complex number.
Return type:: array_like

pmrf.functions.math.magdeg_2_reim(mag, deg)[source]

Convert linear magnitude and phase (in deg) arrays into a complex array.

Parameters:

mag (number or array_like) – Magnitude.
deg (number or array_like) – Phase in degrees.

Returns:

z – A complex number or sequence of complex numbers.

Return type:

array_like

pmrf.functions.math.dbdeg_2_reim(db, deg)[source]

Convert dB magnitude and phase (in deg) arrays into a complex array.

Parameters:

db (number or array_like) – Magnitude in dB.
deg (number or array_like) – Phase in degrees.

Returns:

z – A complex number or sequence of complex numbers.

Return type:

array_like

pmrf.functions.math.db_2_np(db)[source]

Convert a value in decibel (dB) to neper (Np).

Parameters:: db (number or array_like) – A real number or sequence of real numbers.
Returns:: np – A real number of sequence of real numbers.
Return type:: number or array_like

pmrf.functions.math.np_2_db(x)[source]

Convert a value in Nepers (Np) to decibel (dB).

Parameters:: x (number or array_like) – A real number or sequence of real numbers.
Returns:: db – A real number of sequence of real numbers.
Return type:: number or array_like

pmrf.functions.math.radian_2_degree(rad)[source]

Convert angles from radians to degrees.

Parameters:: rad (number or array_like) – Angle in radian.
Returns:: deg – Angle in degree.
Return type:: number or array_like

pmrf.functions.math.degree_2_radian(deg)[source]

Convert angles from degrees to radians.

Parameters:: deg (number or array_like) – Angle in degrees.
Returns:: rad – Angle in radians.
Return type:: number or array_like

pmrf.functions.math.feet_2_meter(feet=1)[source]

Convert length in feet to meter.

1 foot is equal to 0.3048 meters.

Parameters:: feet (number or array-like, optional, default=1) – Length in feet.
Returns:: meter – Length in meter.
Return type:: number or array-like

See also

meter_2_feet

pmrf.functions.math.meter_2_feet(meter=1)[source]

Convert length in meter to feet.

1 meter is equal to 3.28084 feet.

Parameters:: meter (number or array-like, optional, default=1) – Length in meter.
Returns:: feet – Length in feet.
Return type:: number or array-like

See also

feet_2_meter

pmrf.functions.math.db_per_100feet_2_db_per_100meter(db_per_100feet=1)[source]

Convert attenuation values given in dB/100ft to dB/100m.

db_per_100meter = db_per_100feet * rf.meter_2_feet()

Parameters:: db_per_100feet (number or array-like, optional, default=1) – Attenuation in dB/100 ft.
Returns:: db_per_100meter – Attenuation in dB/100 m.
Return type:: number or array-like

pmrf.functions.math.unwrap_rad(phi)[source]

Unwrap a phase given in radians.

Parameters:: phi (number or array_like) – Phase in radians.
Returns:: phi – Unwrapped phase in radians.
Return type:: number of array_like

pmrf.functions.math.sqrt_known_sign(z_squared, z_approx)[source]

Return the square root of a complex number, with sign chosen to match z_approx.

Parameters:

z_squared (number or array-like) – The complex to be square-rooted.
z_approx (number or array-like) – The approximate value of z. The sign of z is chosen to match that of z_approx.

Returns:

z – Square root of z_squared.

Return type:

number, array-like (same type as z_squared)

pmrf.functions.math.find_correct_sign(z1, z2, z_approx)[source]

Create new vector from z1, z2 choosing elements with sign matching z_approx.

This is used when you have to make a root choice on a complex number. and you know the approximate value of the root.

\[z1,z2 = \pm \sqrt(z^2)\]

Parameters:

z1 (array-like) – Root 1.
z2 (array-like) – Root 2.
z_approx (array-like) – Approximate answer of z.

Returns:

z3 – Array built from z1 and z2 by z1 where sign(z1) == sign(z_approx), z2 else.

Return type:

np.array

pmrf.functions.math.find_closest(z1, z2, z_approx)[source]

Return z1 or z2 depending on which is closer to z_approx.

Parameters:

z1 (array-like) – Root 1.
z2 (array-like) – Root 2.
z_approx (array-like) – Approximate answer of z.

Returns:

z3 – Array built from z1 and z2.

Return type:

np.array

pmrf.functions.math.sqrt_phase_unwrap(z)[source]

Take the square root of a complex number with unwrapped phase.

This idea came from Lihan Chen.

\[\sqrt{|z|} \exp( \arg_{unwrap}(z) / 2 )\]

Parameters:: z (number or array_like) – A complex number or sequence of complex numbers.
Returns:: z – A complex number or sequence of complex numbers.
Return type:: number of array_like

pmrf.functions.math.dirac_delta(x)[source]

Calculate Dirac function.

Dirac function \(\delta(x)\) defined as \(\delta(x)=1\) if x=0, 0 otherwise.

Parameters:: x (number of array_like) – A real number or sequence of real numbers.
Returns:: delta – 1 or 0.
Return type:: number of array_like

References

https://en.wikipedia.org/wiki/Dirac_delta_function

pmrf.functions.math.neuman(x)[source]

Calculate Neumans number.

It is defined as:

\[2 - \delta(x)\]

where \(\delta\) is the Dirac function.

Parameters:: x (number or array_like) – A real number or sequence of real numbers.
Returns:: y – A real number or sequence of real numbers.
Return type:: number or array_like

See also

dirac_delta

pmrf.functions.math.null(A, eps=1e-15)[source]

Calculate the null space of matrix A.

Parameters:

A (array_like) – Input matrix.
eps (float, optional, default=1e-15) – Epsilon value for singular value thresholding.

Returns:

null_space – The null space of A.

Return type:

array_like

References

https://scipy-cookbook.readthedocs.io/items/RankNullspace.html https://stackoverflow.com/questions/5889142/python-numpy-scipy-finding-the-null-space-of-a-matrix

pmrf.functions.math.inf_to_num(x)[source]

Convert inf and -inf’s to large numbers.

Parameters:: x (array-like or number) – The input array or number.
Returns:: x – Input without with +/- inf replaced by large numbers.
Return type:: Number of array_like

pmrf.functions.math.cross_ratio(a, b, c, d)[source]

Calculate the cross ratio of a quadruple of distinct points on the real line.

The cross ratio is defined as:

\[r = \frac{ (a-b)(c-d) }{ (a-d)(c-b) }\]

Parameters:

a (array-like or number) – Input points.
b (array-like or number) – Input points.
c (array-like or number) – Input points.
d (array-like or number) – Input points.

Returns:

r – The cross ratio.

Return type:

array-like or number

References

https://en.wikipedia.org/wiki/Cross-ratio

pmrf.functions.math.complexify(f, name=None)[source]

Make a function f(scalar) into f(complex).

If f(x) then it returns f_c(z) = f(real(z)) + 1j*f(imag(z))

If the real/imag arguments are not first, then you may specify the name given to them as kwargs.

Parameters:

f (Callable) – Function of real variable.
name (string, optional) – Name of the real/imag argument names if they are not first.

Returns:

f_c – Function of a complex variable.

Return type:

Callable

Examples

>>> def f(x): return x
>>> f_c = rf.complexify(f)
>>> z = 0.2 -1j*0.3
>>> f_c(z)

pmrf.functions.math.complex2Scalar(z)[source]

Serialize a list/array of complex numbers.

Parameters:: z (number or array_like) – A complex number or sequence of complex numbers.
Returns:: re_im – Produce the following array for an input z: z[0].real, z[0].imag, z[1].real, z[1].imag, etc.
Return type:: array_like

See also

scalar2Complex

pmrf.functions.math.scalar2Complex(s)[source]

Unserialize a list/array of real and imag numbers into a complex array.

Inverse of complex2Scalar().

Parameters:: s (array_like) – An array with real and imaginary parts ordered as: z[0].real, z[0].imag, z[1].real, z[1].imag, etc.
Returns:: z – A complex number or sequence of complex number.
Return type:: Number or array_like

See also

complex2Scalar

pmrf.functions.math.multiply_by(x, by, axis=None)[source]

Broadcast multiply array x by array by along a specified axis.

This function tiles by to match the dimensions of x implied by block multiplication.

Parameters:

x (jnp.ndarray) – Input array.
by (jnp.ndarray) – Array to multiply with.
axis (int, optional) – Axis along which to apply the multiplication (0 for rows, 1 for columns).

Returns:

Result of the multiplication.

Return type:

jnp.ndarray

Raises:

ValueError – If the shape of the specified axis is not divisible by the length of by.

pmrf.functions.math.sum_every(x, n, axis=None)[source]

Sum blocks of size n along a specified axis.

Parameters:

x (jnp.ndarray) – Input array.
n (int) – Block size to sum.
axis (int, optional) – Axis along which to sum (0 for rows, 1 for columns).

Returns:

Resulting summed array.

Return type:

jnp.ndarray

Raises:

ValueError – If the shape of the specified axis is not divisible by n.

pmrf.functions.math.multiply_every(x, n, axis=None)[source]

Multiply blocks of size n along a specified axis.

Parameters:

x (jnp.ndarray) – Input array.
n (int) – Block size to multiply.
axis (int, optional) – Axis along which to multiply (0 for rows, 1 for columns).

Returns:

Resulting product array.

Return type:

jnp.ndarray

Raises:

ValueError – If the shape of the specified axis is not divisible by n.

pmrf.functions.math.convolve_interleaved(x, axis=1)[source]

Convolve interleaved signals (e.g. real/imag parts stored sequentially).

Parameters:

x (jnp.ndarray) – Input array.
axis (int, optional, default=1) – Axis along which to convolve.

Returns:

The convolved result.

Return type:

jnp.ndarray

Raises:

Exception – If the input is not 1D or axis is not 1 (not yet implemented).

pmrf.functions.math.rms(x)[source]

Calculate the Root Mean Square (RMS) of the input.

Parameters:: x (jnp.ndarray) – Input array.
Returns:: The RMS value.
Return type:: float or jnp.ndarray

pmrf.functions.math.mag_2_db(x)[source]

Convert magnitude to decibels.

Parameters:: x (jnp.ndarray) – Linear magnitude.
Returns:: Value in dB.
Return type:: jnp.ndarray

pmrf.functions.math.db_2_mag(x)[source]

Convert decibels to magnitude.

Parameters:: x (jnp.ndarray) – Value in dB.
Returns:: Linear magnitude.
Return type:: jnp.ndarray

pmrf.functions.math.polar_2_rect(radii, angles, deg=False)[source]

Convert polar coordinates to rectangular (complex) coordinates.

Parameters:

radii (jnp.ndarray) – Radius (magnitude).
angles (jnp.ndarray) – Angle (phase).
deg (bool, optional, default=False) – If True, angles are in degrees.

Returns:

Complex number in rectangular coordinates.

Return type:

jnp.ndarray

pmrf.functions.math.rect_2_polar(x, deg=False)[source]

Convert rectangular (complex) coordinates to polar coordinates.

Parameters:

x (jnp.ndarray) – Complex number input.
deg (bool, optional, default=False) – If True, return angle in degrees.

Returns:

radii (jnp.ndarray) – Magnitude.
angles (jnp.ndarray) – Phase angle.

pmrf.functions.math.rsolve(A, B)[source]

Solves x @ A = B.

Calls numpy.linalg.solve with transposed matrices. Equivalent to B @ np.linalg.inv(A) but avoids calculating the inverse explicitely.

Input should have dimension of similar to (nfreqs, nports, nports).

Parameters:

A (np.ndarray) – Matrix A.
B (np.ndarray) – Matrix B.

Returns:

x – Solution matrix.

Return type:

np.ndarray

pmrf.functions.math.nudge_eig(mat, cond=None, min_eig=None)[source]

Nudge eigenvalues with absolute value smaller than max(cond * max(eigenvalue), min_eig) to that value.

Can be used to avoid singularities in solving matrix equations. Input should have dimension of similar to (nfreqs, nports, nports).

Parameters:

mat (np.ndarray) – Matrices to nudge.
cond (float, optional) – Minimum eigenvalue ratio compared to the maximum eigenvalue. Default value is 1e-9.
min_eig (float, optional) – Minimum eigenvalue. Default value is 1e-12.

Returns:

res – Nudged matrices.

Return type:

np.ndarray

pmrf.functions.math.round_sig(x, sig=3)[source]

Round to a specific number of significant digits.

Parameters:

x (float) – Number to round.
sig (int, optional, default=3) – Number of significant digits.

Returns:

Rounded number.

Return type:

float

pmrf.functions.math.comb(N, k, exact=False, repetition=False)[source]

The number of combinations of N things taken k at a time.

This is often expressed as “N choose k”.

When exact=False, the result is approximately and efficiently computed using the following formula:

\[\exp\left\{\ln{\Gamma(N+1)} - [\ln{\Gamma(k+1)} + \ln{\Gamma(N+1-k)}]\right\}\]

using the Gamma function.

Parameters:

N (np.ndarray) – The number of things.
k (np.ndarray) – The number of elements taken.
exact (bool, optional) – If True, the result is computed exactly and returned as an integer type. Currently, vectorization is not supported for exact=True.
repetition (bool, optional) – If repetition is True, then the number of combinations with repetition is computed.

Returns:

comb – The number of combinations of N things taken k at a time.

Return type:

np.ndarray

pmrf.functions.math.evaluate_power_basis(x, coeffs, lower_bound, upper_bound)[source]

Evaluate a polynomial in the power basis.

The input x is normalized to the range [0, 1] based on bounds.

Parameters:

x (jnp.ndarray) – Input values.
coeffs (jnp.ndarray) – Polynomial coefficients.
lower_bound (float) – Lower bound of the domain.
upper_bound (float) – Upper bound of the domain.

Returns:

Evaluated polynomial values.

Return type:

jnp.ndarray

pmrf.functions.math.evaluate_bernstein_basis(x, coeffs, lower_bound, upper_bound)[source]

Evaluate a polynomial in the Bernstein basis.

Parameters:

x (jnp.ndarray) – Input values.
coeffs (jnp.ndarray) – Coefficients (control points) of the Bernstein polynomial.
lower_bound (float) – Lower bound of the domain.
upper_bound (float) – Upper bound of the domain.

Returns:

Evaluated values.

Return type:

jnp.ndarray

pmrf.functions.math.conv_inter(x, axis=1)

Convolve interleaved signals (e.g. real/imag parts stored sequentially).

Parameters:

x (jnp.ndarray) – Input array.
axis (int, optional, default=1) – Axis along which to convolve.

Returns:

The convolved result.

Return type:

jnp.ndarray

Raises:

Exception – If the input is not 1D or axis is not 1 (not yet implemented).

pmrf.functions.math.dB20(x)

Convert magnitude to decibels.

Parameters:: x (jnp.ndarray) – Linear magnitude.
Returns:: Value in dB.
Return type:: jnp.ndarray

pmrf.functions.math.conv_cost(x)