SciPy - funm() Function

---

---

The scipy.linalg.funm() function calculates a function for a square matrix A by applying a mathematical function, such as exponential, logarithmic, or trigonometric. It works by first applying the function on A's eigenvalues and then rebuilding the matrix. It is an flexible approach allows for easy computation of various matrix transformations, including custom functions.

The funm() method is widely applied in physics, engineering, and numerical computation to solve matrix function problems. Its application can be shown in system dynamics, signal processing, quantum physics, and stability analysis based on heavy simulation and analytical needs of matrix functions.

Errors may occur when the matrix A has ill-conditioned eigenvalues or when the function func is not well-defined for those eigenvalues-for example, when logarithm is applied to non-positive eigenvalues. Non-square matrices are not supported and will raise a ValueError.

This method can be combined with others, such as expm(), which is a matrix exponential function, or sqrtm(), the matrix square root, to calculate advanced matrix decompositions, sensitivity analysis, and stability evaluation. These combinations are useful in making it applicable in solving complex problems in real-life applications.

Syntax

The syntax for the SciPy funm() method is as follows −

.funm(A, func, disp=True)

Parameters

This method accepts the following parameters −

• A (N, N) array_like − Input square matrix (nn), real or complex.

• func (callable) − A callable function applied to the eigenvalues of A.

• disp (bool, optional) − If True, warnings for ill-conditioned matrices are displayed. If False, the function also returns an error estimate.

Return Value

• funm (N, N) ndarray − The result of applying the scalar function to the matrix A.

• errest (float) − A measure of the Frobenius norm of the error in the computation.

Example 1 : Matrix Exponential with funm

Using funm(), the exponential function can be applied to all eigenvalues of a square matrix to provide a matrix exponential result. This is especially useful in solving matrix differential equations.

The code below passes a 22 matrix to funm() and uses np.exp as the scalar function. The function applies the exponential on the matrix eigenvalues and returns the matrix exponential.

import numpy as np
from scipy.linalg import funm

# Input: Square matrix
A = np.array([[1, 2], 
              [3, 4]])

# Compute the matrix exponential using funm
exp_matrix = funm(A, np.exp)

print("Matrix Exponential:\n", exp_matrix)

When we run above program, it produces following result

Matrix Exponential:
 [[ 51.9689562   74.73656457]
 [112.10484685 164.07380305]]

Example 2: Matrix Logarithm for Positive Definite Matrices

If the eigenvalues of a square matrix are positive, funm() can be used to compute the natural logarithm. This is useful for spectral analysis and stability calculations.

The example below, uses a 22 positive definite matrix. The funm function applies np.log to the eigenvalues to compute the matrix logarithm.

import numpy as np
from scipy.linalg import funm

# Input: Positive definite matrix
A = np.array([[2, 1], 
              [1, 2]])

# Compute the matrix logarithm using funm
log_matrix = funm(A, np.log)

print("Matrix Logarithm:\n", log_matrix)

Following is an output of the above code

Matrix Logarithm:
 [[0.54930614 0.54930614]
 [0.54930614 0.54930614]]

Example 3: Handling Ill-Conditioned Matrices with Error Estimate

For an ill-conditioned matrix, adding an error estimate to the calculated output with disp=False ensures the numerical dependability.

In the below code, an ill-conditioned matrix A is used as an input, and the presence of small eigenvalues may bring about numerical instability. The function funm() uses the exponential function (exp) over the matrix, and returns a computed matrix exponential and an estimate of the error. The estimation of the error is used for the determination of the precision in the result for reliable sensitive calculations.

import numpy as np
from scipy.linalg import funm

# Input: Ill-conditioned matrix
A = np.array([[1e-5, 1], 
              [0, 1e-5]])

# Compute the matrix exponential with error estimation
exp_matrix, error_estimate = funm(A, np.exp, disp=False)
print("Matrix Exponential:\n", exp_matrix)
print("Error Estimate:", error_estimate)

Output of the above code is as follows

Matrix Exponential:
 [[1.00001 0.     ]
 [0.      1.00001]]
Error Estimate: 1

Example 4: Error Handling for Non-Square Matrices in funm

The funm() method requires a square matrix. Using a non-square matrix generates a ValueError.

Let us create a 23 matrix as input, funm() returns an error due to improper shape. Following is the code −

import numpy as np
from scipy.linalg import funm
# Input: Non-square matrix
A = np.array([[1, 2, 3], 
              [4, 5, 6]])

try:
    # Attempt to compute matrix function
    result = funm(A, np.exp)
except ValueError as e:
    print("Error:", e)

Output of the above code is as follows

Error: expected square array_like input

Example 5: Applying Custom Scalar Functions with funm

The funm() method also enables users to create new scalar functions for complex matrix manipulations. This capability is extremely beneficial for unique applications that require non-standard mathematical calculations.

The code below uses a 33 matrix as input. Using funm(), we build a custom scalar function f(x)=x^2+1 and apply it to the eigenvalues of A. This shows how user-defined functions can be integrated into matrix operations.

import numpy as np
from scipy.linalg import funm
# Input: General matrix
A = np.array([[1, 2, 3], 
              [4, 5, 6], 
              [7, 8, 9]])

# Define a custom scalar function
def custom_func(x):
    return x**2 + 1

# Apply the custom function to the matrix using funm
custom_matrix = funm(A, custom_func)
print("Custom Function Applied Matrix:\n", custom_matrix)

Output of the above code is as follows

Custom Function Applied Matrix:
 [[ 31.  36.  42.]
 [ 66.  82.  96.]
 [102. 126. 151.]]