Math¶

Provides a collection of functions useful in various mathematical calculations.

e13tools.math.gcd(*args)[source]¶

Returns the greatest common divisor of the provided sequence of integers.

Parameters:	args (tuple of int) – Integers to calculate the greatest common divisor for.
Returns:	gcd (int) – Greatest common divisor of input integers.

Example

>>> gcd(18, 60, 72, 138)
6

See also

lcm(): Least common multiple for sequence of integers.

e13tools.math.is_PD(matrix)[source]¶

Checks if matrix is positive-definite or not, by using the cholesky() function. It is required for matrix to be Hermitian.

Parameters:	matrix (2D array_like) – Matrix that requires checking.
Returns:	out (bool) – True if matrix is positive-definite, False if it is not.

Examples

Using a real matrix that is positive-definite (like the identity matrix):

>>> matrix = np.eye(3)
>>> matrix
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])
>>> is_PD(matrix)
True

Using a real matrix that is not symmetric (Hermitian):

>>> matrix = np.array([[1, 2], [3, 4]])
>>> matrix
array([[1, 2],
       [3, 4]])
>>> is_PD(matrix)
Traceback (most recent call last):
    ...
ValueError: Input argument 'matrix' must be Hermitian!

Using a complex matrix that is positive-definite:

>>> matrix = np.array([[4, 1.5+1j], [1.5-1j, 3]])
>>> matrix
array([[ 4.0+0.j,  1.5+1.j],
       [ 1.5-1.j,  3.0+0.j]])
>>> is_PD(matrix)
True

See also

nearest_PD(): Find the nearest positive-definite matrix to the input matrix.

e13tools.math.lcm(*args)[source]¶

Returns the least common multiple of the provided sequence of integers. If at least one integer is zero, the output will also be zero.

Parameters:	args (tuple of int) – Integers to calculate the least common multiple for.
Returns:	lcm (int) – Least common multiple of input integers.

Example

>>> lcm(8, 9, 21)
504

See also

gcd(): Greatest common divisor for sequence of integers.

e13tools.math.nCr(n, r, repeat=False)[source]¶

For a given set S of n elements, returns the number of unordered arrangements (“combinations”) of length r one can make with S. Returns zero if r > n and repeat is False.

Other Parameters:
Parameters:	n (int) – Number of elements in the set S. r (int) – Number of elements in the sub-set of set S.
	repeat (bool. Default: False) – If False, each element in S can only be chosen once. If True, they can be chosen more than once.
Returns:	n_comb (int) – Number of “combinations” that can be made with S.

Examples

>>> nCr(4, 2)
6

>>> nCr(4, 2, repeat=True)
10

>>> nCr(2, 4, repeat=True)
5

>>> nCr(2, 4)
0

See also

nPr(): Returns the number of ordered arrangements.

e13tools.math.nearest_PD(matrix)[source]¶

Find the nearest positive-definite matrix to the input matrix.

Parameters:	matrix (2D array_like) – Input matrix that requires its nearest positive-definite variant.
Returns:	mat_PD (2D `ndarray` object) – The nearest positive-definite matrix to the input matrix.

Notes

This is a Python port of John D’Errico’s nearestSPD code [1], which is a MATLAB implementation of Higham (1988) [2].

According to Higham (1988), the nearest positive semi-definite matrix in the Frobenius norm to an arbitrary real matrix \(A\) is shown to be

\[\frac{B+H}{2},\]

with \(H\) being the symmetric polar factor of

\[B=\frac{A+A^T}{2}.\]

On page 2, the author mentions that all matrices \(A\) are assumed to be real, but that the method can be very easily extended to the complex case. This can indeed be done easily by taking the conjugate transpose instead of the normal transpose in the formula on the above.

References

[1]	https://www.mathworks.com/matlabcentral/fileexchange/42885-nearestspd

[2]	N.J. Higham, “Computing a Nearest Symmetric Positive Semidefinite Matrix” (1988): https://doi.org/10.1016/0024-3795(88)90223-6

Examples

Requesting the nearest PD variant of a matrix that is already PD results in it being returned immediately:

>>> matrix = np.eye(3)
>>> matrix
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])
>>> is_PD(matrix)
True
>>> nearest_PD(matrix)
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])

Using a real non-PD matrix results in it being transformed into an PD-matrix:

>>> matrix = np.array([[1, 2], [3, 4]])
>>> matrix
array([[1, 2],
       [3, 4]])
>>> is_PD(matrix)
Traceback (most recent call last):
    ...
ValueError: Input argument 'matrix' must be Hermitian!
>>> mat_PD = nearest_PD(matrix)
>>> mat_PD
array([[ 1.31461828,  2.32186616],
       [ 2.32186616,  4.10085767]])
>>> is_PD(mat_PD)
True

Using a complex non-PD matrix converts it into the nearest complex PD-matrix:

>>> matrix = np.array([[4, 2+1j], [1+3j, 3]])
>>> matrix
array([[ 4.+0.j,  2.+1.j],
       [ 1.+3.j,  3.+0.j]])
>>> mat_PD = nearest_PD(matrix)
>>> mat_PD
array([[ 4.0+0.j,  1.5-1.j],
       [ 1.5+1.j,  3.0+0.j]])
>>> is_PD(mat_PD)
True

See also

is_PD(): Checks if matrix is positive-definite or not.

e13tools.math.nPr(n, r, repeat=False)[source]¶

For a given set S of n elements, returns the number of ordered arrangements (“permutations”) of length r one can make with S. Returns zero if r > n and repeat is False.

Other Parameters:
Parameters:	n (int) – Number of elements in the set S. r (int) – Number of elements in the sub-set of set S.
	repeat (bool. Default: False) – If False, each element in S can only be chosen once. If True, they can be chosen more than once.
Returns:	n_perm (int) – Number of “permutations” that can be made with S.

Examples

>>> nPr(4, 2)
12

>>> nPr(4, 2, repeat=True)
16

>>> nPr(2, 4, repeat=True)
16

>>> nPr(2, 4)
0

See also

nCr(): Returns the number of unordered arrangements.