Accelerating the pace of engineering and science

# Documentation Center

• Trial Software

# Dom::Matrix

## Syntax

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, [(i1, j1) = value1, (i2, j2) = value2, …])
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, [j1 = value1, j2 = value2, …])
Dom::Matrix(R)(m, 1, Array)
Dom::Matrix(R)(m, 1, List)
Dom::Matrix(R)(m, 1, Table)
Dom::Matrix(R)(m, 1, [i1 = value1, i2 = value2, …])

## 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, to compute the determinant of a square matrix A, call linalg::det(A). The command linalg::gaussJordan(A) performs Gauss-Jordan 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 231.
 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 non-zero 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 non-zero.

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 mn 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 non-empty list. The list must contain mn 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 non-zero 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.

Dom::BaseDomain

## Axioms

If R has Ax::canonicalRep, then Ax::canonicalRep.

Cat::Matrix(R)

## 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

Mat := Dom::Matrix()

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:

A := Mat([[1, 5], [2, 3]])

In the same way, we define the following 2 ⨉ 3 matrix:

B := Mat([[-1, 5/2, 3], [1/3, 0, 2/5]])

and perform matrix arithmetic using the standard arithmetical operators of MuPAD, e.g., the matrix product AB, the fourth power of A as well as the scalar multiplication of A times :

A * B, A ^ 4, 1/3 * A

The matrices A and B have different dimensions, and therefore the sum of A and B is not defined. MuPAD issues an error message:

A + B
Error: The dimensions do not match. [(Dom::Matrix(Dom::ExpressionField()))::_plus]

To compute the inverse of A, just enter:

1/A

If a matrix is not invertible, FAIL is the result of this operation. For example, the matrix:

C := Mat(2, 2, [[2]])

is not invertible, hence:

C^(-1)

delete A, B, C:

### Example 2

We create the domain of matrices over the coeffcient ring Dom::ExpressionField():

Mat := Dom::Matrix()

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:

A := Mat([[1, 2], [2, 4]])

linalg::rank(A)

Use linalg::eigenvectors to compute eigenvalues and eigenvectors of the matrix A:

linalg::eigenvectors(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":

linalg::gaussElim(A) = A::dom::gaussElim(A)[1]

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:

A::dom::gaussElim(A, ColumnElimination)

delete A:

### Example 3

We create the default matrix domain Dom::Matrix(). As a shortcut, this domain can also be created via matrix:

A := matrix([[ 1, 2, 3, 4],
[ 2, 0, 4, 1],
[-1, 0, 5, 2]])

domtype(A)

Matrix components can be extracted by the index operator []:

A[2, 1] * A[1, 2] - A[3, 1] * A[1, 3]

If one of the indices is not in its valid range, an error message is issued. Assignments to matrix components are performed similarly:

delete a:
A[1, 2] := a^2: A

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:

A[2..3, 1..3]

The index operator does not allow to insert submatrices into a given matrix. This is implemented by the function linalg::substitute.

delete A:

### 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:

MatZ19 := Dom::Matrix(Dom::IntegerMod(19)):
MatZ19([[1, 2], [2]])

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:

MatZ19(4, 4, [[1, 2], [2]])

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:

MatZ19([[2, 3], [-1, I]])
Error: Cannot define a matrix over 'Dom::IntegerMod(19)'. [(Dom::Matrix(Dom::IntegerMod(19)))::new]
delete MatZ19:

### 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):

Dom::Matrix()(2, 2, (i, j) -> 1/(i + j - 1))

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:

delete x:
Dom::Matrix()(2, 2, x), Dom::Matrix()(2, 2, (i, j) -> x)

### Example 6

Diagonal matrices can be created with the option Diagonal and a list of diagonal components:

Mat := Dom::Matrix():
Mat(3, 4, [1, 2, 3], Diagonal)

Hence, to define the n ⨉ n identity matrix, you can enter:

Mat(3, 3, [1 \$ 3], Diagonal)

or call:

Mat(3, 3, x -> 1, Diagonal)

The easiest way to create the identity matrix, however, is to use the method "identity":

Mat::identity(3)

delete Mat:

### Example 7

Toeplitz matrices can be defined with the option Banded. The following call defines a three-banded matrix with the component 2 on the main diagonal and the component - 1 on the first subdiagonal and superdiagonal:

Dom::Matrix()(4, 4, [-1, 2, -1], Banded)

### 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:

delete a, b:
A := Dom::Matrix()(
[[(a - b)^2, a^2 + b^2], [a^2 + b^2, (a - b)*(a + b)]]
)

enter:

expand(A)

If you want to differentiate the matrix components, then call for example:

diff(A, a)

To substitute matrix components by some values, enter:

subs(A, a = 1, b = -1)

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:

A := Dom::Matrix()([[4, 2], [9, 3]]):
B := Dom::Matrix()([[2, 1], [3,-1]]):
zip(A, 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:

C := Dom::Matrix()(
[[sin(x)^2 + cos(x)^2, cos(x)*tan(x)],
[(a^2 - b^2)/(a + b), 1]]
)

call:

map(C, Simplify)

delete A, B, C:

### 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:

diff(f(matrix([[a*x^2, b], [c, d]])), x)

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:

diff(matrix([[a*x^2, b], [c, d]]), x)

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:

Mat := Dom::Matrix():
v := Mat(2, 1, [1, 2])

The dimension of this vector is:

Mat::matdim(v)

The length of a vector may also be queried by linalg::vecdim or nops(v):

linalg::vecdim(v)

The ith component of this vector can be extracted in two ways: either by v[i, 1] or by v[i]:

v[1], v[2]

We compute the 2-norm of v by the following call:

norm(v, 2)

delete Mat, v:

### Example 11

We create random matrices over the field of the rational numbers. Consider a random matrix A1 with 3 rows and 3 columns:

Mat := Dom::Matrix(Dom::Rational):
A1 := Mat::random(3, 3)

A second matrix A2 should contain at most 2 non-zero entries. We can create such a matrix by using 2 as the third argument for random:

A2 := Mat::random(3, 3, 2)

The product of these matrices is given by

C := A1 * A2

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 non-zero entries:

C::dom::doprint(C)

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 non-zero entries:

X := Mat::random(100, 200, 6):  print(X)
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]

Warning: This matrix is too large for display.
If you want to see all nonzero entries of a matrix, say A, then call
'A::dom::doprint(A)'. [(Dom::Matrix(Dom::Rational))::print]
Warning: This matrix is too large for display.
If you want to see all nonzero entries of a matrix, say A, then call
'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 array-like structure of dimension 100 ⨉ 200 with (integer) zeroes in the empty places. The sparse print mode should be used:

X::dom::doprint(X)

For convenience, there is a function doprint that calls this method by just entering:

doprint(X)

delete Mat, A1, A2, C, X:

## Parameters

 R A ring, i.e., a domain of category Cat::Rng. The default ring is Dom::ExpressionField(). Array A one- or two-dimensional 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 i-th subdiagonal are initialized with the (h + 1 - i)-th element of List. All elements of the i-th 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.

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 non-zero, 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 xy 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(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 floating-point 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 floating-point approximation of the exponential of A if A*t contains at least one floating-point number and all entries can be converted to floating-point 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 — Scalar-matrix 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 — Floating-point approximation of the matrix components

float(A)

This method only exists if R implements the method "float".

 Note:   Usually the floating-point approximations are not elements of R! For example, Dom::Integer implements such a method, but the floating-point approximation of an integer cannot be re-converted 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, fraction-free 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 zero-test.

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(A)

### 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 1-norm 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 (2-norm) 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 k-norm 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 2-norm 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(A)

nonZeroes(A)

### nonZeroOperands — Return a sequence of all non-zero operands

nonZeroOperands(A)

This method is useful for retrieving information on the non-zero 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 non-zero 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 ≤ pmn.

When calling the "random" method with four parameters, a sparse matrix with m rows, n columns and at most p non-zero 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 ≤ pmn.

### 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 floating-point 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 B2 = 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(A, B)

### tr — Trace of a square matrix

tr(A)

If A is not square, an error message is issued.

transpose(A)

## 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

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

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

concatMatrix(A, B, …)

### 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 non-zero 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 non-zero 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.

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!

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.

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 component-wise

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 run-time 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 non-zero 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 TeX-representation 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 non-trivial 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 non-trivial 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 non-trivial 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(A)

### 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).