numeric
::fMatrix
Functional calculus for numerical square matrices
MuPAD® notebooks are not recommended. Use MATLAB® live scripts instead.
MATLAB live scripts support most MuPAD functionality, though there are some differences. For more information, see Convert MuPAD Notebooks to MATLAB Live Scripts.
numeric::fMatrix(f
, A
, p_{1}, p_{2}, …
, options
)
numeric::fMatrix(f, A)
computes the matrix f(A) with
a function f and
a square matrix A.
If no return type is specified via the option ReturnType
= d
, the domain type of the result depends on the type of
the input matrix A
:
For a dense matrix A of
type Dom::DenseMatrix()
the result is a dense matrix
of type Dom::DenseMatrix()
over the ring of MuPAD^{®} expressions.
For all other matrices A of
category Cat::Matrix
,
the result is returned as a matrix
of
type Dom::Matrix()
over the ring of MuPAD expressions.
This includes input matrices A
of type Dom::Matrix(...)
, Dom::SquareMatrix(...)
, Dom::MatrixGroup(...)
etc.
The components of A must
not contain symbolic objects which cannot be converted to numerical
values via float
.
Numerical symbolic expressions such as π, , etc.
are accepted. They are converted to floats.
When you use numeric::fMatrix
, the matrix
must be diagonalizable, and all its elements must be convertible to
floatingpoint numbers. Otherwise, use funm
.
If numeric::fMatrix
detects numerically that A is
not diagonalizable, it aborts with an error message . Nevertheless,
the numerical algorithm often fails to detect that the matrix is not
diagonalizable, and the returned matrix is dominated by roundoff
effects. When usingnumeric::fMatrix
, ensure the
diagonalization is possible and well conditioned.
Symmetric/Hermitian and skew/skew Hermitian matrices can always
be diagonalized in a numerically stable way; numeric::fMatrix
produces
reliable numerical results for such matrices.
The procedure f must accept complex floatingpoint numbers as first argument. It may return arbitrary MuPAD expressions, provided these can be multiplied with floatingpoint numbers.
The parameters p_{1}, p_{2},
…
may be numerical or symbolic objects. They must be accepted
by f
as 2nd argument, 3rd argument etc.
In contrast to the components of A,
numerical symbolic objects such as π, etc.
passed as parameters p_{1}, p_{2},
…
are not converted to floats.
Inversion or exponentiation of a matrix may be realized with
the functions and exp
, respectively. However,
it is recommended to use the specialized algorithms numeric::inverse
and numeric::expMatrix
instead.
Also matrix evaluation of low degree polynomials should be done with
standard matrix arithmetic rather than with numeric::fMatrix
.
The function is sensitive to the environment variable DIGITS
,
which determines the numerical working precision.
We compute the matrix power A^{100}:
A := array(1..2, 1..2, [[2, PI], [exp(10), 0]]): numeric::fMatrix(x > x^100, A)
Alternatively, you may use the function _power
which takes the exponent as a
second parameter:
numeric::fMatrix(_power, A, 100)
delete A:
We compute the square root of a matrix:
A := matrix([[0, 1], [1, 1]]): B := numeric::fMatrix(sqrt, A)
The small imaginary parts are caused by numerical roundoff. We eliminate them by extracting the real parts of the components:
B := map(B, Re)
We verify that B^2
is A
.
Since A was
passed as a matrix of type Dom::Matrix()
, the matrix B is
also of this type. We may compute the square by the overloaded standard
arithmetic using the operator ^
:
B^2
delete A, B:
We compute with a symbolic parameter t:
A := array(1..2, 1..2, [[0, 1], [1, 0]]): numeric::fMatrix(exp@_mult, A, t*PI)
delete A:
We demonstrate the difference between HardwareFloats
and SoftwareFloats
.
The diagonalization of the following matrix is illconditioned. The
result is dominated by roundoff effects:
A := array(1..3, 1..3, [[10, 1, 1 ], [ 0, 1, 1 ], [ 1, 0, 10^(14)]]): numeric::fMatrix(ln, A, SoftwareFloats)
numeric::fMatrix(ln, A, HardwareFloats)
In the following case, the roundoff effects of SoftwareFloats
makes
the algorithm think that the matrix cannot be diagonalized. Consequently, FAIL
is
returned. With HardwareFloats
, however, a result
is computed:
A := array(1..3, 1..3, [[ 1 , 1 , 1 ], [ 0 , 1 , 1 ], [ 10^(30), 0 , 10^(30)]]): numeric::fMatrix(ln, A, SoftwareFloats)
numeric::fMatrix(ln, A, HardwareFloats)
delete A:

A procedure representing a scalar function or , where P is a set of parameters 

A square matrix of domain type 

Arbitrary MuPAD objects accepted by f as additional input parameters 

With With Compared to the If no If the result cannot be computed with hardware floats, software arithmetic by the MuPAD kernel is tried. If the current value of There may be several reasons for hardware arithmetic to fail:
If neither If NoteFor illconditioned matrices, the result is subject to roundoff
errors. The results returned with 

Suppresses warnings 

Option, specified as Return the result as a matrix of domain type 
Depending on the type of the input matrix A
,
the matrix f(A) is
returned as a matrix of type DOM_ARRAY
, DOM_HFARRAY
, Dom::Matrix()
or Dom::DenseMatrix()
.
If the algorithm thinks that A
is not diagonalizable,
then FAIL
is
returned.
A numerical diagonalization A = X diag(λ_{1}, λ_{2}, …) X^{ 1} is computed. The columns of X are the (right) eigenvectors of A, the diagonal entries λ_{1}, λ_{2}, … are the corresponding eigenvalues. The function f is mapped to the eigenvalues, the matrix result is computed by
.
The eigenvector matrix X may
be obtained via numeric::eigenvectors(A)[2]
.
The condition number of the eigenvector matrix is a measure indicating how well conditioned the diagonalization of the matrix A is. If this number is larger than 10^{DIGITS}, then not a single digit of the diagonalization data is trustworthy.
The call numeric::fMatrix(exp, A)
corresponds
to numeric::expMatrix(A, Diagonalization)
.