Syntax
Domain Creation
Dom::Matrix(<R
>)
Element Creation
Dom::Matrix(R)(Array
)
Dom::Matrix(R)(List
)
Dom::Matrix(R)(ListOfRows
)
Dom::Matrix(R)(Matrix
)
Dom::Matrix(R)(m
, n
)
Dom::Matrix(R)(m
, n
, Array
)
Dom::Matrix(R)(m
, n
, List
)
Dom::Matrix(R)(m
, n
, ListOfRows
)
Dom::Matrix(R)(m
, n
, Table
)
Dom::Matrix(R)(m
, n
, [(i_{1}, j_{1}) = value_{1}, (i_{2}, j_{2}) = value_{2}, …]
)
Dom::Matrix(R)(m
, n
, f
)
Dom::Matrix(R)(m
, n
, List
, Diagonal)
Dom::Matrix(R)(m
, n
, g
, Diagonal)
Dom::Matrix(R)(m
, n
, List
, Banded)
Dom::Matrix(R)(1
, n
, Array
)
Dom::Matrix(R)(1
, n
, List
)
Dom::Matrix(R)(1
, n
, Table
)
Dom::Matrix(R)(1
, n
, [j_{1} = value_{1}, j_{2} = value_{2}, …]
)
Dom::Matrix(R)(m
, 1
, Array
)
Dom::Matrix(R)(m
, 1
, List
)
Dom::Matrix(R)(m
, 1
, Table
)
Dom::Matrix(R)(m
, 1
, [i_{1} = value_{1}, i_{2} = value_{2}, …]
)
Description
Domain Creation
Dom::Matrix(R)
creates domains of matrices
over a component domain R
of category Cat::Rng
(a ring, possibly
without unit).
If the optional parameter R
is not given, Dom::ExpressionField()
is
used as component domain. Matrices of this type accept arbitrary MuPAD^{®} expressions
(numbers, symbols etc.) as entries. The name matrix
is an alias for this default matrix
domain Dom::Matrix()
.
A vector with n entries
is either an n×1 matrix
(a column vector), or a 1×n matrix
(a row vector).
Arithmetical operations with matrices can be performed by using
the standard arithmetical operators of MuPAD.
E.g., if A
and B
are two
matrices defined by Dom::Matrix(R)
, A
+ B
computes the sum, and A * B
computes
the product of the two matrices, provided that the dimensions are
appropriate.
Similarly, A^(1)
or 1/A
computes
the inverse of a square matrix A
if it exists.
Otherwise, FAIL
is
returned. See Example 1.
Many system functions are overloaded for matrices, such as map
, subs
, has
, zip
, E.g., use conjugate
to compute
the complex conjugate of a matrix, norm
to compute matrix norms, or exp
to compute the exponential
of a matrix.
Most of the functions in the MuPAD linear algebra package linalg work
with matrices. For example, the command linalg::gaussJordan(A)
performs
GaussJordan elimination on A
to transform A
to
its reduced row echelon form.
See the documentation of linalg for
a list of available functions of this package.
The domain Dom::Matrix(R)
represents matrices
over R
of arbitrary size. Therefore, it does not
have any algebraic structure (other than being a set of
matrices).
In this help page, we use the following notations for a matrix A (an
element of Dom::Matrix(R)
):
nrows(A) denotes
the number of rows of A.
ncols(A) denotes
the number of columns of A.
A row index is an integer in
the range from 1 to nrows(A).
A column index is an integer
in the range from 1 to ncols(A).
Note:
The number of rows and columns, respectively, of a matrix must
be less than 2^{31}. 
Note:
The components of a matrix are no longer evaluated after the
creation of the matrix, i.e., if they contain free identifiers they
will not be replaced by their values. 
Element Creation
Dom::Matrix(R)(Array)
and Dom::Matrix(R)(Matrix)
create
a new matrix with the dimension and the components of Array
and Matrix
,
respectively.
The components of Array
or Matrix
are
converted to elements of the domain R
. An error
message is issued if one of these conversions fails.
The creation of (sparse) matrices via arrays is useful for matrices
of moderate size. Note that indexed assignments to arrays are much
faster than the corresponding indexed assignments to matrices. However,
since all elements of the array (including the zeroes) need to be
filled in before conversion to a (sparse) matrix, memory is wasted
for very large and very sparse matrices. In such a situation, one
should define a table containing only the nonzero elements and convert
the table to a matrix (see below).
Dom::Matrix(R)(List)
creates an m×1 column
vector with components taken from the nonempty list,
where m is
the number of entries of List
.
One may also use a list of equations to create an object of Dom::Matrix
.
In this case the entries of the list must be of the form (i,
j) = value
, where i
and j
denote
the row and column index and value
the coefficient
of the matrix. i
and j
need
to be positive integers.
Dom::Matrix(R)(ListOfRows)
creates an m×n matrix
with components taken from the nested list ListOfRows
,
where m is
the number of inner lists of ListOfRows
, and n is
the maximal number of elements of an inner list. Each inner list corresponds
to a row of the matrix. Both m and n must
be nonzero.
If an inner list has less than n entries,
the remaining components in the corresponding row of the matrix are
set to zero.
The entries of the inner lists are converted to elements of
the domain R
. An error message is issued if one
of these conversions fails.
The call Dom::Matrix(R)(m, n)
returns the m×n zero
matrix.
Use the method "identity"
to create the n×n identity
matrix.
The call Dom::Matrix(R)(m, n, Array)
creates
an m×n matrix
with components taken from Array
, which must be
an array or an hfarray. Array
must
have m n operands.
The first m operands
define the first row, the next m operands
define the second row, etc. The formatting of the array is irrelevant.
E.g., any array with 6 elements
can be used to create a matrix of dimension 1
×6, or 2×3,
or 3×2, or 6
×1.
Dom::Matrix(R)(m, n, List)
creates an m×n matrix
with components taken row after row from the nonempty list. The list must contain m n entries.
Dom::Matrix(R)(m, n, ListOfRows)
creates
an m×n matrix
with components taken from the list ListOfRows
.
If m ≥ 2 and n ≥
2, then ListOfRows
must consist
of at most m
inner lists, each having at most n
entries.
The inner lists correspond to the rows of the returned matrix.
If an inner list has less than n
entries,
the remaining components of the corresponding row of the matrix are
set to zero. If there are less than m
inner lists,
the remaining lower rows of the matrix are filled with zeroes.
Dom::Matrix(R)(m, n, Table)
creates an m×n matrix
with components taken from the table Table
.
By defining the entries of the table first, one can easily create
large and sparse matrices. The entry Table[i, j]
of
the table will be the entry in the i
th row and
the j
th column of the matrix. Therefore, the table
needs to be indexed by positive integers i
and j
.
Dom::Matrix(R)(m, n, [(i1, j1) = value1, (i2, j2) =
value2, ...])
is a further way to create a matrix specifying
only the nonzero entries A[i1, j1] = value1
, A[i2,
j2] = value2
etc. The ordering of the entries in the input
list is irrelevant.
Dom::Matrix(R)(m, n, f)
returns the matrix
whose (i, j)th
component is the value of the function call f(i, j)
.
The row index i ranges
from 1 to m and
the column index j from 1 to n.
The function values are converted to elements of the domain R
.
An error message is issued if one of these conversions fails.
Dom::Matrix(R)(1, n, Array)
returns the 1
×n row vector with components
taken from Array
. The array
or hfarray
Array
must
have n
entries.
The entries of the array are converted to elements of the domain R
.
An error message is issued if one of these conversions fails.
Dom::Matrix(R)(1, n, List)
returns the 1
×n row vector with components
taken from List
. The list List
must
have at most n
entries. If there are fewer entries,
the remaining vector components are set to zero.
The entries of the list are converted to elements of the domain R
.
An error message is issued if one of these conversions fails.
Dom::Matrix(R)(1, n, Table)
returns the 1
×n row vector with components
taken from Table
. The table Table
must
not have more than n
entries. If there are fewer
entries, the remaining vector components are regarded as zero.
Dom::Matrix(R)(m, 1, Array)
returns the m×1 column
vector with components taken from Array
. The array
or hfarray
Array
must
have m
entries.
The entries of the array are converted to elements of the domain R
.
An error message is issued if one of these conversions fails.
Dom::Matrix(R)(m, 1, List)
returns the m×1 column
vector with components taken from List
. The list List
must
have at most m
entries. If there are fewer entries,
the remaining vector components are set to zero.
The entries of the list are converted to elements of the domain R
.
An error message is issued if one of these conversions fails.
Dom::Matrix(R)(m, 1, Table)
returns the m×1 column
vector with components taken from Table
. The table Table
must
have no more than m
entries. If there are fewer
entries, the remaining vector components are regarded as zero.
Examples
Example 1
Whenever possible, one should use Dom::ExpressionField
()
as
the coefficient domain of matrices – therefore Dom::ExpressionField
()
is
the default coefficient domain of matrices.
The components of matrices over Dom::ExpressionField
()
can
be arbitrary arithmetical expressions. Consider
We assigned the domain to the identifier Mat
and
now we can define a matrix A of
two rows, where each row is a list of two elements by the following
line:
In the same way, we define the following 2
×3 matrix:
and perform matrix arithmetic using the standard arithmetical
operators of MuPAD, e.g., the matrix product A B,
the fourth power of A as
well as the scalar multiplication of A times
:
The matrices A and B have
different dimensions, and therefore the sum of A and B is
not defined. MuPAD issues an error message:
Error: The dimensions do not match. [(Dom::Matrix(Dom::ExpressionField()))::_plus]
To compute the inverse of A,
just enter:
If a matrix is not invertible, FAIL
is the
result of this operation. For example, the matrix:
is not invertible, hence:
Example 2
We create the domain of matrices over the coeffcient ring Dom::ExpressionField()
:
Beside standard matrix arithmetic, the library linalg offers
many functions dealing with matrices. For example, if one wants to
compute the rank of a matrix, use linalg::rank
:
Use linalg::eigenvectors
to
compute eigenvalues and eigenvectors of the matrix A:
Try info(linalg)
for a list of available
functions, or enter help(linalg)
for details about
the library linalg.
Some of the functions in the linalg
package
simply serve as "interface" functions for methods of
a matrix domain described above. For example, linalg::transpose
uses the method "transpose"
to
get the transposed matrix. The function linalg::gaussElim
applies Gaussian elimination
to a matrix by calling the method "gaussElim"
:
In contrast to the methods of the domain Dom::Matrix(R)
,
the corresponding functions of the linalg
packages
do extended checking of their input parameters. Note that there might
be minor differences in the functionality of the linalg
functions
and the matrix methods. E.g., the option ColumnElimination
is
not available in linalg::gaussElim
, but only in
the "gaussElim"
method of the matrix domain:
Example 3
We create the default matrix domain Dom::Matrix()
.
As a shortcut, this domain can also be created via matrix
:
Matrix components can be extracted by the index operator []
:
If one of the indices is not in its valid range, an error message
is issued. Assignments to matrix components are performed similarly:
Beside the usual indexing of matrix components, it is also possible
to extract submatrices from a given matrix. The following call creates
the submatrix of A which
consists of the rows 2 to 3 and columns 1 to 3 of A:
The index operator does not allow to insert submatrices into
a given matrix. This is implemented by the function linalg::substitute
.
Example 4
In the following examples, we demonstrate the different ways
of creating matrices. We work with matrices defined over the field ℤ_{19},
i.e., the field of integers modulo 19.
This component ring can be created with the domain constructor Dom::IntegerMod
.
We start by giving a list of rows, where each row is a list
of row entries:
The elements of the two inner lists, the row entries, were converted
to elements of the domain Dom::IntegerMod(19)
.
The number of rows is the number of sublists of the argument,
i.e., m = 2.
The number of columns is determined by the length of the inner list
with the most entries, which is the first inner list with two entries.
Missing entries in the other inner lists are treated as zero components.
The call:
fixes the dimension of the matrix. Missing entries and inner
lists are treated as zero components and zero rows, respectively.
An error message is issued if one of the given entries cannot
be converted to an element over ℤ_{19}:
Error: Cannot define a matrix over 'Dom::IntegerMod(19)'. [(Dom::Matrix(Dom::IntegerMod(19)))::new]
Example 5
This example illustrates how to create a matrix with components
given as values of an index function. First we create the 2
×2 Hilbert matrix (see also the functions linalg::hilbert
and linalg::invhilbert
):
Note the difference when working with expressions and functions.
If you give an expression it is treated as a function in the row and
column indices:
Example 6
Diagonal matrices can be created with the option Diagonal
and
a list of diagonal components:
Hence, to define the n×n identity
matrix, you can enter:
or call:
The easiest way to create the identity matrix, however, is to
use the method "identity"
:
Example 7
Toeplitz matrices can be defined with the option Banded
.
The following call defines a threebanded matrix with the component 2 on
the main diagonal and the component  1 on
the first subdiagonal and superdiagonal:
Example 8
Some system functions can be applied to matrices, such as norm
, expand
, diff
, conjugate
, or exp
.
For example, to expand the components of the matrix:
enter:
If you want to differentiate the matrix components, then call
for example:
To substitute matrix components by some values, enter:
The function zip
can
also be applied to matrices. The following call combines two matrices A and B by
dividing each component of A by
the corresponding component of B:
The quoted character `/`
is another notation
for the function _divide
, the functional form of
the division operator /
.
If one needs to apply a function to the components of a matrix,
then use the function map
.
For example, to simplify the components of the matrix:
call:
Example 9
However, there may appear some unexpected results using the
function diff
in
the context of matrices. The derivative of the following unspecified
function f
of a matrix is computed due to the chain
rule:
Usually, the function f
would implicitly
be assumed to be scalar. Hence, the derivative of f
should
be scalar as well. In the above situation the chain rule is applied
for differentiation: the inner function is the matrix containing the
symbolic components a*x^2
, b
, c
and d
.
Its derivative is computed by simply applying diff
to each component of the matrix:
Finally, the exterior unspecified function f
is
implicitly assumed to be scalar, such that each component of the derivative
of the inner function is multiplied by the exterior differentiation.
Example 10
A column vector is represented by a 2×1 matrix:
The dimension of this vector is:
The length of a vector may also be queried by linalg::vecdim
or nops(v)
:
The ith
component of this vector can be extracted in two ways: either by v[i,
1]
or by v[i]
:
We compute the 2norm of v
by the following
call:
Example 11
We create random matrices over the field of the rational numbers.
Consider a random matrix A1
with 3 rows and 3 columns:
A second matrix A2
should contain at most
2 nonzero entries. We can create such a matrix by using 2 as the
third argument for random
:
The product of these matrices is given by
By default, matrices are displayed like 'dense' arrays with
zeroes in the empty places. For sparse matrices of large column and/or
row dimension, such a 'dense' print mode is not appropriate: formatting
of the print output would be very time consuming. Further, a 'dense'
print output is not very informative for sparse matrices. For this
reason, the "doprint"
method provides a sparse
output mode printing only the nonzero entries:
With this method, one can also print large sparse matrices.
We create a random sparse matrix with 100 rows, 200 columns and at
most 6 nonzero entries:
Warning: This matrix is too large for display. To see all nonzero entries of a matrix A, use 'A::dom::doprint(A)'. [(Dom::Matrix(Dom::Rational))::print]
The warning speaks for itself. X
is regarded
as 'too large for display' since, with the default 'dense' output
mode, the sparse matrix would be printed as a huge arraylike structure
of dimension 100×200 with
(integer) zeroes in the empty places. The sparse print mode should
be used:
For convenience, there is a function doprint
that calls this method by just
entering:
Parameters
R

A ring, i.e., a domain of category Cat::Rng . The default ring is Dom::ExpressionField() .

Array

A one or twodimensional array or hfarray

Matrix

A matrix, i.e., an element of a domain of category Cat::Matrix

m , n

Matrix dimension (positive integers)

List

A list of matrix components

ListOfRows

A list of at most m rows; each row given
as a list of at most n matrix components

Table

A table of coefficients of the matrix for sparse input

f

A function or
a functional
expression with two parameters (the row and column index)

g

A function or a functional expression with one parameter (the
row index)

Options
Diagonal

Create a diagonal matrix
With the option Diagonal , diagonal matrices
can be created with diagonal elements taken from a list, or computed by a function or
a functional
expression.
Dom::Matrix(R)(m, n, List, Diagonal) creates
the m×n diagonal
matrix, whose diagonal elements are the entries of List .
List must have at most min(m, n) entries.
If it has fewer elements, the remaining diagonal elements are set
to zero.
The entries of List are converted to elements
of the domain R . An error message is issued if
one of these conversions fails.
Dom::Matrix(R)(m, n, g, Diagonal) returns
the sparse matrix whose ith
diagonal element is g(i, i) , where the index i runs
from 1 to min(m, n).
The function values are converted to elements of the domain R .
An error message is issued if one of these conversions fails.

Banded

Create a Toeplitz matrix
Dom::Matrix(R)(m, n, List, Banded) creates
an m×n Toeplitz
matrix with the elements of List as entries. The
number of entries of List must be odd, say 2 h +
1, and must not exceed 2 min(m, n)
 1. The bandwidth of the resulting matrix is
at most 2 h + 1.
A Toeplitz matrix is a matrix where the elements of each band
are identical. See also Example 7.
All elements of the main diagonal of the created matrix are
initialized with the middle element of List . All
elements of the ith
subdiagonal are initialized with the (h +
1  i)th element of List .
All elements of the ith
superdiagonal are initialized with the (h +
1 + i)th element of List .
All entries on the remaining sub and superdiagonals are set to zero.
The entries of List are converted to elements
of the domain R . An error message is issued if
one of these conversions fails.

Entries
"isSparse"  is always TRUE . 
"randomDimen"  is set to [10, 10] . See the method "random" below
for details. 
Methods
expand all
Mathematical Methods
_divide
— Divide matrices
_divide(A
, B
)
An error message is issued if the dimensions of A
and B
do
not match.
This method only exists if R
is a commutative
ring with a unit, i.e., a domain of category Cat::Ring
.
This method overloads the system function _divide
for matrices,
i.e., one may use it in the form A / B
, or in functional
notation: _divide(A, B)
.
_invert
— Compute the inverse of a matrix
_invert(A
, Normal =
b
)
This method only exists if R
is a domain
of category Cat::Ring
.
This method overloads the system function _invert
for matrices, i.e., one may use
it in the form 1/A
or A^(1)
,
or in functional notation: _invert(A)
.
If Normal = TRUE
, then the matrix inverse
is always returned in a normalized form. For details about normalization,
see normal
.
If Normal = FALSE
, then the matrix inverse can
appear in a normalized form, but normalization is not guaranteed.
By default Normal = TRUE
.
Normal
affects the results only if a matrix
contains variables or exact expressions, such as sqrt(5)
or sin(PI/7)
.
_mod
— Map the modulo operator to the elements of a matrix
_mod(A
, n
)
n
must be nonzero, and a mod n
must
be defined for every entry a
of A
.
This method overloads the function _mod
for matrices; one
may use it in the form A mod n
, or in functional
notation: _mod(A, n)
.
_mult
— Multiplie matrices by matrices, vectors and scalars
_mult(x
, y
)
_mult(x
, y
)
If y
is of the domain type R
or
can be converted to such an element, the corresponding scalar multiplication
is computed.
Otherwise, y
is converted to a matrix of
the domain type of x
. If this conversion fails,
this method calls the method "_mult"
of the domain
of y
giving all arguments in the same order.
If x
is a matrix of the same domain type
as y
, the matrix product x y is
computed. An error message is issued if the dimensions of the matrices
do not match.
If x
is of the domain type R
or
can be converted to such an element, the corresponding scalar multiplication
is computed.
Otherwise, x
is converted to a matrix of
the domain type of y
. If this conversion fails, FAIL
is
returned.
This method handles more than two arguments by calling itself
recursively with the first half of all arguments and the last half
of all arguments. Then the product of these two results is computed
with the system function _mult
.
This method overloads the system function _mult
for matrices,
i.e., one may use it in the form x * y
, or in functional
notation: _mult(x, y)
.
_negate
— Negate a matrix
_negate(A
)
This method overloads the system function _negate
for matrices, i.e., one may use
it in the form A
, or in functional notation: _negate(A)
.
_plus
— Add matrices
_plus(A
, B, …
)
The arguments A, B , ...
are converted to
matrices of the domain type Dom::Matrix(R)
. FAIL
is
returned if one of these conversions fails.
This method overloads the system function _plus
for matrices,
i.e., one may use it in the form A + B
, or in functional
notation: _plus(A, B)
.
_power
— Integer power of a matrix
_power(A
, n
)
If the power n
is a negative integer then A
must
be nonsingular and R
must be a domain of category Cat::IntegralDomain
. Otherwise FAIL
is
returned.
If n
is zero and the component ring R
is
a ring with no unit (i.e., of category Cat::Rng
, but not of category Cat::Ring
), FAIL
is
returned.
This method overloads the system function _power
for matrices, i.e., one may use
it in the form A^n
, or in functional notation: _power(A,
n)
.
conjugate
— Complex conjugate of a matrix
conjugate(A
)
This method only exists if R
implements the
method "conjugate"
, which computes the complex
conjugate of an element of the domain R
.
This method overloads the system function conjugate
for matrices, i.e., one may
use it in the form conjugate(A)
.
cos
— Cosine of a matrix
cos(A
)
If A
is not square, an error message is issued.
If the component domain of A
does not allow the
computation of cos(elem)
for an arbitrary element elem
of
the component ring, FAIL
is returned.
This method uses the function numeric::expMatrix
for a floatingpoint
approximation of the exponential of A
if A
is
defined over the domain Dom::Float
.
If some eigenvalues of A
do not exist in R
or
cannot be computed, then FAIL
is returned.
In the symbolic case the functions exp
and linalg::jordanForm
are called. The latter
may not be able to compute the Jordan form of A
.
In this case FAIL
is returned.
This method only exists if R
is a domain
of category Cat::Field
.
This method overloads the function cos
for matrices, i.e., one may use it
in the form cos(A)
.
diff
— Differentiation of matrix components
diff(A, …
)
This method only exists if R
implements the
method "diff"
.
This method overloads the system function diff
for
matrices, i.e., one may use it in the form diff(A, ...)
.
See Example 8 and Example 9.
equal
— Equality test of matrices
equal(A
, B
)
Note that if R
has the axiom Ax::systemRep
then normal
is
used to simplify the components of A
and B
before
testing their equality.
exp
— Exponential of a matrix
exp(A
, <t
>)
If A
is not square, an error message is issued.
If the component domain of A
does not allow the
computation of exp(elem)
for an arbitrary element elem
of
the component ring, FAIL
is returned.
This method uses the function numeric::expMatrix
for a floatingpoint
approximation of the exponential of A
if A*t
contains
at least one floatingpoint number and all entries can be converted
to floatingpoint numbers.
If some eigenvalues of A
do not exist in R
or
cannot be computed, then FAIL
is returned.
In the symbolic case, the function linalg::jordanForm
is called, which may
not be able to compute the Jordan form of A
. In
this case FAIL
is returned.
This method only exists if R
is a domain
of category Cat::Field
.
This method overloads the system function exp
for matrices, i.e., one may use it
in the form exp(A, ...)
.
expand
— Expand matrix components
expand(A
)
This method only exists if R
implements the
method "expand"
, or if R
has
the axiom Ax::systemRep
(in
this case, the system function expand
is used).
This method overloads the system function expand
for matrices, i.e., one may use
it in the form expand(A)
.
factor
— Scalarmatrix factorization
factor(A
)
The factor s is
the gcd of all components of the matrix A
. Hence,
this method only exists if R
is of category Cat::GcdDomain
.
This method overloads the system function factor
for matrices, i.e., one may use
it in the form factor(A)
.
float
— Floatingpoint approximation of the matrix components
float(A
)
This method only exists if R
implements the
method "float"
.
Note:
Usually the floatingpoint approximations are not elements of R !
For example, Dom::Integer implements
such a method, but the floatingpoint approximation of an integer
cannot be reconverted to an integer. This method checks whether the resulting matrix can be converted
to the domain type of A only if testargs() returns TRUE (e.g.,
if one calls this method from the interactive level of MuPAD). Otherwise, one has to take care that the matrix returned is
compatible with its component ring. 
fourier
— Fourier transform of the matrix components
fourier(A
, t
, s
)
This method overloads the function fourier
for matrices.
gaussElim
— Gaussian elimination for matrices
gaussElim(A
, <ColumnElimination>)
With the option ColumnElimination
, the matrix A is
reduced to a lower triangular echelon form via elementary column operations
(without ColumnElimination
, the Gauss algorithm
uses elementray row operations to obtain the
upper echelon form). The following relation holds: transpose(gaussElim(A,
ColumnElimination)[1]) = gaussElim(transpose(A))[1]
. With ColumnElimination
,
the last entry of the returned list is the set of characteristic column indices
of A.
For very large m×n matrices A with m much
greater n,
the column elimination is faster than the row elimination.
If the matrix is not square, i.e., the determinant of A
is
not defined, then the third entry of the returned list is the value FAIL
.
This method only exists if the component ring R
is
an integral domain, i.e., a domain of category Cat::IntegralDomain
.
If R
has the method "pivotSize"
,
the pivot element of smallest size is chosen at every pivoting step,
whereby pivotSize
must return a positive integer
representing the "size" of an element.
If no such method is defined, Gaussian elimination without a
pivot strategy is applied to A
.
If R
has the axiom Ax::efficientOperation
("_invert")
and
is of category Cat::Field
,
ordinary Gaussian elimination is used. Otherwise, fractionfree elimination
is performed on A
.
If R
implements the method "normal"
,
it is used to simplify subsequent computations of the Gaussian elimination
process.
Note that if R
does not implement the method "normal"
,
but the elements of R
are represented by kernel
domains, i.e., R
has the axiom Ax::systemRep
, the system function normal
is
used instead.
identity
— Identity matrix
identity(n
)
This method only exists if the component ring R
is
of category Cat::Ring
,
i.e., a ring with unit.
int
— Integration of matrix components
int(A, …
)
This method only exists if R
implements the
method "int"
.
This method overloads the system function int
for
matrices, i.e., one may use it in the form int(A, ...)
.
ifourier
— Inverse Fourier transform of the matrix components
ifourier(A
, s
, t
)
This method overloads the function ifourier
for matrices.
ilaplace
— Inverse Laplace transform of the matrix components
ilaplace(A
, s
, t
)
This method overloads the function ilaplace
for matrices.
iszero
— Test for zero matrices
iszero(A
)
Note that there may exist more than one representation of the
zero matrix of a given dimension if R
does not
have Ax::canonicalRep
.
If R
implements the method "normal"
,
it is used to simplify the components of A
for
the zerotest.
Note that if R
does not implement such a
method, but the elements of R
are represented by
kernel domains, i.e., R
has the axiom Ax::systemRep
, the system
function normal
is
used instead.
This method overloads the system function iszero
for matrices, i.e., one may use
it in the form iszero(A)
.
laplace
— Laplace transform of the matrix components
laplace(A
, t
, s
)
This method overloads the function laplace
for matrices.
matdim
— Matrix dimension
norm
— Norm of matrices and vectors
norm(A
, Infinity)
norm(A
, Maximum)
norm(v
, Infinity)
norm(v
, Maximum)
norm(A
, Frobenius)
norm(A
, 1)
norm(v
, Euclidean)
norm(v
, k
)
norm(A, Maximum)
computes the maximum norm
of the matrix A
, which is the maximum row sum (the
row sum is the sum of norms of each component in a row).
If the domain R
does not implement the methods "max"
and "norm"
, FAIL
is
returned.
Using norm(v, Infinity)
for a vector v
the
maximum norm of all elements is returned.
If the domain R
does not implement the methods "max"
and "norm"
, FAIL
is
returned.
Using norm(v, Maximum)
for a vector v
the
maximum norm of all elements is returned.
If the domain R
does not implement the methods "max"
and "norm"
, FAIL
is
returned.
norm(A, Frobenius)
computes the Frobenius
norm of A
, which is the square root of the sum
of the squares of the norms of each component.
If the result is no longer an element of the domain R
,
or if R
does not implement the method "norm"
, FAIL
is
returned.
norm(A, 1)
computes the 1norm of the matrix A
,
which is the maximum sum of the norms of the elements of each column.
If R
does not implement the methods "max"
and "norm"
, FAIL
is
returned.
norm(v, Euclidean)
computes the Euclidean
norm (2norm) of the vector v
,
which is defined to be the square root of the sum of the norms of
the elements of v
raised to the square.
FAIL
is returned if the result is no longer
an element of the domain R
. The function linalg::scalarProduct
is
used to compute the Euclidean norm of the vector v
.
If R
does not implement the method "norm"
, FAIL
is
returned.
norm(v, k)
computes the knorm
of the vector v
, which is defined to be the kth
root of the sum of the norms of the elements of v
raised
to the kth
power.
FAIL
is returned if the result is no longer
an element of the domain R
. For k =
2, the function linalg::scalarProduct
is used to compute
the 2norm of v
.
If R
does not implement the method "norm"
, FAIL
is
returned.
The method norm
overloads the function norm
for matrices, i.e.,
one may use it in the form norm(A k )
, where k
is
either Infinity
, Frobenius
,
or a positive integer. The default value of k
is Infinity
.
normal
— Simplification of matrix components
normal(A
)
If R
does not implement the method "normal"
,
but the elements of R
are represented by kernel
domains, i.e., R
has the axiom Ax::systemRep
, the system function normal
is
applied to the components of A
. Otherwise normal(A)
returns A
without
any changes.
This method overloads the system function normal
for matrices,
i.e., one may use it in the form normal(A)
.
nonZeros
— Number of nonzero components of a matrix
nonZeroes
— Number of nonzero components of a matrix
nonZeroOperands
— Return a sequence of all nonzero operands
nonZeroOperands(A
)
This method is useful for retrieving information on the nonzero
entries. For example, to find out the types of the entries in the
matrix, one should not consider all operands op(A)
,
because this would also involve the zero entries. For large matrices
with few entries, it is much more efficient to use this method to
extract the entries.
random
— Random matrix generation
random()
random(g
)
random(m
, n
)
random(m
, n
, g
)
random(m
, n
, p
)
random(m
, n
, p
, g
)
The dimension of the matrix is also chosen randomly. The matrix
size is limited by the values "randomDimen"
(see
"Entries" above). To change the value of the entry "randomDimen"
,
one must first unprotect the domain Dom
(see unprotect
for details).
When calling the "random"
method with one
parameter g
, this parameter is regarded as a random
generator. The matrix entries are created by the calls g()
which
must return elements of the coefficient ring R
.
The dimension of the matrix is chosen randomly as above.
When calling the "random"
method with two
positive integers m
and n
, a
random matrix with m
rows and n
columns
is created. Its elements are generated by the method "random"
of
the component ring R
. If R::random
does
not exist, FAIL
is
returned.
random(m,n,g)
creates a matrix with m
rows
and n
columns. The third parameter g
is
regarded as a random generator. The matrix entries are created by
the calls g()
which must return elements of the
coefficient ring R
.
When calling the "random"
method with positive
integers m
, n
and a nonnegative
integer p
, a sparse matrix with m
rows, n
columns
and at most p
nonzero entries is created. These
entries are generated by the function "random"
of
the component ring R
. If R::random
does
not exist, FAIL
is
returned.
The integer p
must satisfy 0
≤ p ≤ m n.
When calling the "random"
method with four
parameters, a sparse matrix with m
rows, n
columns
and at most p
nonzero entries is created. The
fourth parameter g
is regarded as a random generator.
The matrix entries are created by the calls g()
which
must return elements of the coefficient ring R
.
The integer p
must satisfy 0
≤ p ≤ m n.
sin
— Sine of a matrix
sin(A
)
If A
is not square, an error message is issued.
If the component domain of A
does not allow the
computation of sin(elem)
for an arbitrary element elem
of
the component ring, FAIL
is returned.
This method uses the function numeric::expMatrix
for a floatingpoint
approximation of the exponential of A
if A
is
defined over the domain Dom::Float
.
If some eigenvalues of A
do not exist in R
or
cannot be computed, then FAIL
is returned.
In the symbolic case the functions exp
and linalg::jordanForm
are called. The latter
may not be able to compute the Jordan form of A
.
In this case FAIL
is returned.
This method only exists if R
is a domain
of category Cat::Field
.
This method overloads the function sin
for matrices, i.e., one may use it
in the form sin(A)
.
sqrt
— Square root of a matrix
sqrt(A
, <sqrtfunc
>)
Returned is a matrix B with B^{2} = A such
that the eigenvalues of B are
the square roots of the eigenvalues of A or FAIL
if
the square root of the matrix does not exist. For computing the square
roots of the eigenvalues a function satisfying sqrtfunc(a)^{2} = a for
every element a of
the coefficient ring of A can
be given as optional second argument.
For details we refer to the help page of the function linalg::sqrtMatrix
.
testeq
— Testing for equality of two matrices
tr
— Trace of a square matrix
tr(A
)
If A
is not square, an error message is issued.
transpose
— Transpose of a matrix
Access Methods
_concat
— Horizontal concatenation of matrices
_concat(A
, B, …
)
This method overloads the system function _concat
for matrices, i.e., one may use
it in the form A . B . ...
, or in functional notation: _concat(A,
B, ...)
.
_index
— Matrix indexing
_index(A
, i
, j
)
_index(A
, r1 .. r2
, c1
.. c2
)
_index(v
, i
)
_index(v
, i1 .. i2
)
If i
and j
are not integers,
the call of this method returns in its symbolic form (of type "_index"
)
with evaluated arguments.
Otherwise an error message is given, if i
and j
are
not valid row and column indices, respectively.
Note:
Note that this method uses the system function context to evaluate
the entry in the context of the calling environment. 
_index(A,r1..r2,c1..c2)
returns the submatrix
of A
created by the rows of A
with
indices from r1
to r2
and the
columns of A
with indices from c1
to c2
.
This method returns the ith
entry of the vector v
.
An error message is issued if v
is not a
vector.
If i
is not an integer, the call of _index(v,i)
returns
in its symbolic form (of type "_index"
) with evaluated
arguments.
Otherwise an error message is given, if i
is
less than one or greater than the dimension of v
.
Note:
Note that this method uses the system function context to evaluate
the entry in the context of the calling environment. 
_index(v,i1..i2)
returns the subvector of v
,
formed by the entries with index i1
to i2
.
See also the method "op"
.
An error message is issued if v
is not a
vector.
_index
overloads the system function _index
for matrices,
i.e., one may use it in the form A[i, j]
, A[r1..r2,
c1..c2]
, v[i]
and v[i1..i2]
,
respectively, or in functional notation: _index(A, ...)
.
addCol
— Addition of a multiple of one column to the multiple of another column
addCol(A
, i
, j
, f
,
<g
>)
i
and j
must be positive
integers smaller than or equal to the number of columns of the matrix A
.
If f
and g
are not elements
of the coefficient domain R
of the matrix A
and
cannot be converted to R
, FAIL
is
returned.
addRow
— Addition of a multiple of one row to the multiple of another row
addRow(A
, i
, j
, f
, g
)
i
and j
must be positive
integers smaller than or equal to the number of rows of the matrix A
.
If f
and g
are not elements
of the coefficient domain R
of the matrix A
and
cannot be converted to R
, FAIL
is
returned.
concatMatrix
— Horizontal concatenation of matrices
col
— Extracting a column of a matrix
col(A
, c
)
An error message is issued if c
is less than
one or greater than the number of columns of A
.
delCol
— Deleting a column of a matrix
delCol(A
, c
)
NIL
is returned if A
consists
of only one column.
An error message is issued if c
is less than
one or greater than the number of columns of A
.
delRow
— Deleting a row of a matrix
delRow(A
, r
)
NIL
is returned if A
consists
of only one row.
An error message is issued if r
is less than
one or greater than the number of rows of A
.
evalp
— Evaluating matrices of polynomials at a certain point
evalp(A
, x = a, …
)
This method is only defined if R
is a polynomial
ring of category Cat::Polynomial
.
This method overloads the system function evalp
for
matrices, i.e., one may use it in the form evalp(A, x = a)
.
length
— Length of a matrix
length(A
)
This method overloads the system function length
for
matrices, i.e., one may use it in the form length(A)
.
map
— Apply a function to matrix components
map(A
, f
,
<p1, p2, …
>)
Note:
Note that values returned by f are converted
to elements of the domain R only if testargs() returns TRUE (i.e.,
if one calls this method from the interactive level of MuPAD). If testargs() returns FALSE ,
one must guarantee that f returns elements of the
domain type R . Otherwise, the resulting matrix
will have components which are not elements of the component ring R ! 
Note:
If the function f does not map the zero element
of the component ring to the zero element, a sparse matrix will change
into a dense matrix. This may lead to memory problems when dealing
with very large (sparse) matrices. 
Note that there is the method "mapNonZeroes"
which
maps a function to the nonzero entries of the matrix only.
This method overloads the system function map
for
matrices, i.e., one may use it in the form map(A, f p1 ,
p2 , , …)
.
mapNonZeroes
— Apply a function to the nonzero components of a (sparse) matrix
mapNonZeroes(A
, f
,
<p1, p2, …
>)
multCol
— Multiplication of one column by a scalar factor
multCol(A
, i
, f
)
i
must be a positive integer smaller than
or equal to the number of columns of the matrix A
.
If f
is not an element of the coefficient
domain R
of the matrix A
and
cannot be converted to R
, FAIL
is
returned.
multRow
— Multiplication of one row by a scalar factor
multRow(A
, i
, f
)
i
must be a positive integer smaller than
or equal to the number of rows of the matrix A
.
If f
is not an element of the coefficient
domain R
of the matrix A
and
cannot be converted to R
, FAIL
is
returned.
nops
— Number of components of a matrix
nops(A
)
This method overloads the system function nops
for matrices, i.e., one may use
it in the form nops(A)
.
op
— Component of a matrix
op(A
, i
)
op(A
)
This method returns an expression sequence of all components
of A
.
See also the method "_index"
.
This method overloads the system function op
for matrices, i.e., one may use it
in the form op(A, i)
and op(A)
,
respectively.
row
— Extracting a row from a matrix
row(A
, r
)
An error message is issued if r
is less than
one or greater than the number of rows of A
.
setCol
— Replacing a column of a matrix
setCol(A
, c
, v
)
An error message is issued if c
is less than
one or greater than the number of rows of A
.
setRow
— Replacing a row of a matrix
setRow(A
, r
, v
)
An error message is issued if r
is less than
one or greater than the number of rows of A
.
stackMatrix
— Vertical concatenation of matrices
stackMatrix(A
, B, …
)
An error message is issued if the given matrices do not have
the same number of columns.
subs
— Substitution of matrix components
subs(A, …
)
Note:
Note that the function values are converted to elements of the
domain R only if testargs() returns TRUE (e.g.,
if one calls this method from the interactive level of MuPAD). If testargs() returns FALSE ,
one must guarantee that f returns elements of the
domain type R . Otherwise, the resulting matrix,
which is of domain type Dom::Matrix(R) , would have
components which are not elements of the domain R ! 
This method overloads the system function subs
for
matrices, i.e., one may use it in the form subs(A, ...)
.
subsex
— Extended substitution of matrix components
subsex(A, …
)
Note:
Note that the results of the substitutions are converted to
elements of the domain R only if testargs() returns TRUE (e.g.,
if one calls this method from the interactive level of MuPAD). If testargs() returns FALSE ,
one must guarantee that the results of the substitutions are of the
domain type R , otherwise the resulting matrix,
which is of domain type Dom::Matrix(R) , would have
components which are not elements of the domain R ! 
This method overloads the system function subsex
for
matrices, i.e., one may use it in the form subsex(A, ...)
.
subsop
— Operand substitution of matrix components
subsop(A
, i = x, …
)
Note:
Note that x is converted to the domain R only
if testargs() returns TRUE (e.g.,
if one calls this method from the interactive level of MuPAD). If testargs() returns FALSE , x must
be an element of R , otherwise the resulting matrix,
which is of domain type Dom::Matrix(R) , would have
components which are not elements of the domain R ! 
See also the method "set_index"
.
This method overloads the system function subsop
for
matrices, i.e., one may use it in the form subsop(A, ...)
.
swapCol
— Swapping matrix columns
swapCol(A
, c1
, c2
)
swapCol(A
, c1
, c2
, r1
.. r2
)
An error message is issued if one of the column indices is less
than one or greater than the number of columns of A
.
swapCol(A,c1,c2,r1..r2)
swaps the column
with index c1
and the column with index c2
of A
,
but by taking only those column components which lie in the rows with
indices r1
to r2
.
An error message is issued if one of the column indices is less
than one or greater than the number of columns of A
,
or if one of the row indices is less than one or greater than the
number of rows of A
.
swapRow
— Swapping matrix rows
swapRow(A
, r1
, r2
)
swapRow(A
, r1
, r2
, c1
.. c2
)
An error message is issued if one of the row indices is less
than one or greater than the number of rows of A
.
swapCol(A,r1,r2,c1..c2)
swaps the row with
index r1
and the row with index r2
of A
,
but by taking only those row components which lie in the columns with
indices c1
to c2
.
An error message is issued if one of the row indices is less
than one or greater than the number of rows of A
,
or if one of the column indices is less than one or greater than the
number of columns of A
.
set_index
— Setting matrix components
set_index(A
, i
, j
, x
)
set_index(v
, i
, x
)
Note:
Note that x is converted into an element
of the domain R only if testargs returns TRUE and i and j are
integers (e.g., if one calls this method from the interactive level
of MuPAD). If x is a matrix of the same type
as A or can be converted into a matrix of the same
type as A and the indices i or j are
ranges corresponding to a submatrix of A , then x replaces
the corresponding submatrix in A . Otherwise one has to take care that x is
of domain type R . 
See also the method "subsop"
.
set_index(v,i,x)
replaces the ith
entry of the vector v
by x
.
set_index
on vectors overloads the function set_index
for
matrices, i.e., one may use it in the form A[i, j] := x
and v[i]
:= x
, respectively, or in functional notation: A
:= set_index(A, i, j, x)
or v := set_index(v, i,
x)
.
zip
— Combine matrices componentwise
zip(A
, B
, f
,
<p1, p2, …
>)
The row number of the matrix returned is the minimum of the
row numbers of A
and B
. Its
column number is the minimum of the column numbers of A
and B
.
Note:
Note that the values returned by f are converted
to elements of the domain R only if testargs() returns TRUE (i.e.,
if one calls this method from the interactive level of MuPAD). If testargs() returns FALSE ,
one must guarantee that f returns elements of the
domain type R . Otherwise, the resulting matrix
will have components which are not elements of the component ring R ! 
This method overloads the system function zip
for matrices, i.e., one may use it
in the form zip(A, B, f p1 , p2 , , …)
.
Conversion Methods
convert
— Conversion to a matrix
convert(x
)
FAIL
is returned if the conversion fails.
x
may either be an array, a matrix, or a
list (of sublists, see the parameter ListOfRows
in
"Creating Elements" above). Their entries must then
be convertible into elements of the domain R
.
convert_to
— Matrix conversion
convert_to(A
, T
)
T
may either be DOM_ARRAY
, DOM_LIST
,
or a domain constructed by Dom::Matrix
or Dom::SquareMatrix
. The
elements of A
must be convertible into elements
of the domain R
.
Use the function expr
to
convert A
into an object of a kernel domain (see
below).
create
— Defining matrices without component conversions
create(x, …
)
This method works more efficiently than if one creates matrices
by calling the method "new"
of the domain, because
it avoids any conversion of the components. One must guarantee that
the components have the correct domain type, otherwise runtime errors
can be caused.
expr
— Conversion of a matrix to an object of a kernel domain
expr(A
)
The result is an array representing the matrix A
where
each entry is an object of a kernel domain.
This method overloads the system function expr
for matrices, i.e., one may use
it in the form expr(A)
.
expr2text
— Conversion of a mtrix to a string
expr2text(A
)
This method overloads the system function expr2text
for matrices, i.e., one may
use it in the form expr2text(A)
.
TeX
— TeX formatting of a matrix
TeX(A
)
Note that in the case of very large matrices the output will
not be useful. For printing large matrices use the function "doprint"
to
obtain a sparse matrix output displaying all nonzero entries. Alternatively,
use the matrix slot "setPrintMaxSize"
to set the
maximal size of matrices that will be printed like "dense"
arrays with zero entries displayed as the integer 0.
The method "TeX"
of the component ring R
is
used to get the TeXrepresentation of each component of A
.
This method is used by the function generate::TeX
.
Technical Methods
assignElements
— Multiple assignment to matrices
assignElements(A, …
)
The assigned components must have the domain type R
,
an implicit conversion of the components into elements of domain type R
is
not performed.
This method overloads the system function assignElements
for
matrices, i.e., one may use it in the form assignElements(A,
...)
.
mkSparse
— Conversion of an array or a list of lists to a sparse structure
mkSparse(Array
)
mkSparse(List
)
mkSparse(r
, c
, List
)
The 'sparse structure' s
is a list of c
univariate
polynomials that is used to store the nontrivial elements of the
columns of matrices.
mkSparse(List)
tries to convert the list List
into
a a sparse structure. The result is either FAIL
if
this is not possible, or the list [s, [r, c]]
,
where the positive integers r
and c
are
the dimension of the corresponding matrix. The 'sparse structure' s
is
a list of univariate polynomials that is used to store the nontrivial
elements of the columns of matrices.
See the parameters List
and ListOfRows
in
"Creating Elements" above for admissible formats of List
.
The matrix is regarded as a column or a row vector, if r
or c
is
equal to one. T
mkSparse(r,c,List)
tries to convert the list List
into
a sparse structure representing a matrix of dimension r
times c
.
The result is either FAIL
if this is not
possible, or the list [s, [r, c]]
. The 'sparse
structure' s
is a list of univariate polynomials
that is used to store the nontrivial elements of the columns of matrices.
The matrix is regarded as a column or a row vector, if r
or c
is
equal to one. T
print
— Printing matrices
print(A
)
Note:
Note that it will not be useful to print very large sparse matrices
with lots of zero coefficients in this way – printing such
matrices can be done by using the function "doprint" . 
Use the matrix slot "setPrintMaxSize"
to
set the maximal size of matrices that will be printed like "dense"
arrays with zero entries displayed as the integer 0.
doprint
— Printing large sparse matrices
setPrintMaxSize
— Set the maximal size of matrices that will be printed like "dense" arrays
setPrintMaxSize(printMaxSize
)
The value of the parameter printMaxSize
may
also be infinity
.
In this case, matrices of arbitrary size are printed like "dense"
arrays.
This method returns the previous value of printMaxSize
.
The default value is printMaxSize
= 500.
unapply
— Create a procedure from a matrix
unapply(A
, <x, …
>)
This method overloads the system function fp::unapply
for
matrices, i.e., one may use it in the form fp::unapply(A)
.
See Also
MuPAD Domains
MuPAD Functions