## `Dom::MatrixGroup` -- the Abelian group of m x n matrices

#### Introduction

`Dom::MatrixGroup``(m, n, R)` creates the Abelian group of m x n matrices over the component ring R.

#### Domain

`Dom::MatrixGroup(m, n <, R>)`

#### Parameters

`m, n` | - | positive integers (matrix dimension)
`R` | - | a commutative ring, i.e., a domain of category `Cat::CommutativeRing`; default is `Dom::ExpressionField()`

#### Details

- `Dom::MatrixGroup``(m, n, R)` creates a domain which represents the Abelian group of m x n matrices over the component ring `R`, i.e., it is a domain of category `Cat::AbelianGroup`.
- The domain `Dom::ExpressionField()` is used as the component ring for the matrices if the optional parameter `R` is not given.
- For matrices of a domain created by `Dom::MatrixGroup``(m, n, R)`, matrix arithmetic is implemented by overloading the standard arithmetical operators `+, -, *, /` and `^`. All functions of the `linalg` package dealing with matrices can be applied.
- `Dom::MatrixGroup``(m, n, R)` has the domain `Dom::Matrix(R)` as its super domain, i.e., it inherits each method which is defined by `Dom::Matrix(R)` and not re-implemented by `Dom::MatrixGroup``(m, n, R)`.

  Methods described below are implemented by `Dom::MatrixGroup`.

- The domain `Dom::Matrix(R)` represents matrices over `R` of arbitrary size, and it therefore does not have any algebraic structure (except of being a set of matrices).

  The domain `Dom::SquareMatrix(n, R)` represents the ring of n x n matrices over R.

#### Creating Elements

``Dom::MatrixGroup`(m, n, R)(Array)`
``Dom::MatrixGroup`(m, n, R)(Matrix)`
``Dom::MatrixGroup`(m, n, R)( <m, n>)`
``Dom::MatrixGroup`(m, n, R)( <m, n, >List)`
``Dom::MatrixGroup`(m, n, R)( <m, n, >ListOfRows)`
``Dom::MatrixGroup`(m, n, R)( <m, n, >f)`
``Dom::MatrixGroup`(m, n, R)( <m, n, >List, Diagonal)`
``Dom::MatrixGroup`(m, n, R)( <m, n, >g, Diagonal)`
``Dom::MatrixGroup`(m, n, R)( <m, n, >List, Banded)`

#### Parameters

`Array` | - | an `m` x `n` array
`Matrix` | - | an `m` x `n` matrix, i.e., an element of a domain of category `Cat::Matrix`
`List` | - | a list of matrix components
`ListOfRows` | - | a list of at most `m` rows; each row is a list of at most `n` matrix components
`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
`Banded` | - | create a banded Toeplitz matrix

#### Categories

`Cat::Matrix(R)`

, `Cat::AbelianGroup`

if `R` has `Cat::Field`, then
`Cat::VectorSpace(R)`

#### Related Domains

`Dom::Matrix`, `Dom::SquareMatrix`

#### Details

- `Dom::MatrixGroup``(m, n, R)(Array)` and `Dom::MatrixGroup``(m, n, R)(Matrix)` create a new matrix formed by the entries of `Array` and `Matrix`, respectively.

  The components of `Array` and `Matrix`, respectively, are converted into elements of the domain `R`. An error message is issued if one of these conversions fails.

- The call `Dom::MatrixGroup``(m, n, R)( <m, n>)` returns the m x n zero matrix. Note that the m x n zero matrix can also be found in the entry `"zero"` (see below).
- `Dom::MatrixGroup``(m, n, R)( <m, n, >List)` creates an m x n matrix with components taken from the list `List`.

  This call is only allowed for m x 1 or 1 x n matrices, i.e., if either `m` or `n` is equal to one.

  If the list has too few entries, the remaining components of the matrix are set to zero.

  The entries of the list are converted into elements of the domain `R`. An error message is issued if one of these conversions fails.

- `Dom::MatrixGroup``(m, n, R)( <m, n, >ListOfRows)` creates an m x n matrix with components taken from the nested list `ListOfRows`. Each inner list corresponds to a row of the matrix.

  If an inner list has less than `n` entries, the remaining components in 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.

  The entries of the inner lists are coerced into elements of the domain `R`. An error message is issued if one of these conversions fails.

- `Dom::MatrixGroup``(m, n, 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 coerced into elements of the domain `R`. An error message is issued if one of these conversions fails.

#### Option: Diagonal

- With the option Diagonal, diagonal matrices can be created with diagonal elements taken from a list, or computed by a function.
- `Dom::MatrixGroup``(m, n, R)( <m, n, >List, Diagonal)` creates the m x 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, then the remaining diagonal elements are set to zero.

  The entries of `List` are coerced into elements of the domain `R`. An error message is issued if one of these conversions fails.

- `Dom::MatrixGroup``(m, n, R)( <m, n, >g, Diagonal)` returns the matrix whose ith diagonal element is `g(i)`, where the index i runs from 1 to min(n,m).

  The function values are coerced into elements of the domain `R`. An error message is issued if one of these conversions fails.

#### Option: Banded

- With the option Banded, banded matrices can be created.

  A banded matrix has all entries zero outside the main diagonal and some of the adjacent sub- and superdiagonals.

- `Dom::MatrixGroup``(m, n, R)( <m, n, >List, Banded)` creates an m x n banded Toeplitz matrix with the elements of `List` as entries. The number of entries of `List` must be odd, say 2h+1, and must not exceed `n`. The resulting matrix has bandwidth at most 2h+1.

  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 into elements of the domain `R`. An error message is issued if one of these conversions fails.

#### Entries

one

  is only defined if `m` is equal to `n`; in that case it defines the n x n identity matrix.

randomDimen

  is set to `[m, n]`.

zero

  is the m x n zero matrix.

#### Method evalp: evaluating matrices of polynomials at a certain point

- `evalp(dom A, equation x = a...)`
- - This method evaluates the polynomial components of `A` at the point `x = a`. See the system function `evalp` for details.

    The matrix returned is of the domain `Dom::MatrixGroup``(m, n, R::coeffRing)`, if the evaluation of each component leads to an element of the coefficient ring of the polynomial domain. Otherwise the matrix returned is of the domain of `A`.

  - This method is only defined if `R` is a polynomial ring of category `Cat::Polynomial`.
  - This method overloads the function `evalp` for matrices, i.e., one may use it in the form `evalp(A, x = a)`.

#### Method identity: identity matrix

- `identity(positive integer k)`
- - This method returns the k x k identity matrix.

  - The matrix returned is of the domain `Dom::Matrix(R)`, if `m`<>`n` or if `k`<>`n`.

#### Method matdim: matrix dimension

- `matdim(dom A)`
- - This method returns the list `[m, n]`, i.e., the matrix dimension of `A`.

#### Method random: random matrix generation

- `random()`
- - This method returns a random m x n matrix.
  - The components of the random matrix are randomly generated with the method `"random"` of the component ring `R`.

#### Method _concat: horizontally concatenation of matrices

- `_concat(dom A, dom B...)`
- - This method appends the matrices `B`... to the right side of the matrix `A`.
  - An error message is issued if the given matrices do not have the same number of rows.

  - The returned matrix is of the domain `Dom::Matrix(R)`.

  - This method overloads the function `_concat` for matrices, i.e., one may use it in the form `A . B . ...`, or in functional notation: `_concat(A, B, ...)`.

#### Method _index: matrix indexing

- `_index(dom A, row index i, column index j)`
- - Returns the (i,j)-th entry of the matrix `A`.
  - This method overloads the function `_index` for matrices, i.e., one may use it in the form `A[i, j]` or in functional notation: `_index(A, i, j)`.
- `_index(dom A, row-range r1..r2, column-range 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`.

  - The submatrix is of the domain `Dom::Matrix(R)`.

- `_index(dom A, index i)`
- - This method returns the ith entry of `A`.
  - This call is only allowed for 1 x n or m x 1 matrices, i.e., either `m` or `n` must be equal to one. Otherwise an error message is issued.
- `_index(dom A, index-range i1..i2)`
- - This method returns the subvector of `A`, formed by the entries with index `i1` to `i2` (see also the method `"op"`).
  - This call is only allowed for 1 x n or m x 1 matrices, i.e., either `m` or `n` must be equal to one. Otherwise an error message is issued.
  - This method overloads the function `_index` for matrices, i.e., one may use it in the form `A[i,j]`, `A[r1..r2,c1..c2]`, `A[i]` or `A[i1..i2]`, respectively, or in functional notation: `_index(A...)`.

#### Method concatMatrix: horizontally concatenation of matrices

- `concatMatrix(dom A, dom B...)`
- - This method is identical to the method `"_concat"`.

#### Method col: extracting a column

- `col(dom A, column index c)`
- - This method extracts the column with index `c` of the matrix `A` and returns it as a column vector, i.e., as an element of the domain `Dom::Matrix(R)`.
  - An error message is issued if `c` is less than one or greater than `n`.

#### Method delCol: deleting a column

- `delCol(dom A, column index c)`
- - This method returns the matrix obtained by deleting the column with index `c` of the matrix `A`.
  - `NIL` is returned if `A` only consists of one column.

  - The returned matrix is of the domain `Dom::Matrix(R)`.

  - An error message is issued if `c` is less than one or greater than `n`.

#### Method delRow: deleting a row

- `delRow(dom A, row index r)`
- - This method returns the matrix obtained by deleting the row with index `r` of the matrix `A`.
  - `NIL` is returned if `A` only consists of one row.

  - The returned matrix is of the domain `Dom::Matrix(R)`.

  - An error message is issued if `r` is less than one or greater than `m`.

#### Method row: extracting a row

- `row(dom A, row index r)`
- - This method extracts the row with index `r` of the matrix `A` and returns it as a row vector, i.e., as an element of domain `Dom::Matrix(R)`.
  - An error message is issued if `r` is less than one or greater than `m`.

#### Method stackMatrix: concatenating of matrices vertically

- `stackMatrix(dom A, dom B...)`
- - This method stacks the matrix `A` on the top of the matrix `B`. If further arguments are given, then the result is stacked on the top of the third matrix, and so on.
  - An error message is issued if the given matrices do not have the same number of columns.

  - The matrix returned is of the domain `Dom::Matrix(R)`.

#### Method convert: conversion into a matrix

- `convert(any x)`
- - This method tries to convert `x` into a matrix of type `Dom::MatrixGroup``(m, n, R)`.
  - `FAIL` is returned if the conversion fails.
  - `x` may either be an `m` x `n` array, or an `m` x `n` matrix of category `Cat::Matrix`.

    `x` can also be a list. See the parameter `List` and `ListOfRows` in ``Creating Elements'' above for admissible values of `x`.

    The entries of `x` must be convertable into elements of the domain `R`, otherwise `FAIL` is returned.

#### Example 1

A lot of examples can be found on the help page of the domain constructor `Dom::Matrix`, and most of them are also examples for working with domains created by `Dom::MatrixGroup`. This example only highlights some differences with respect to working with matrices of the domain `Dom::Matrix(R)`.

The following command defines the abelian group of 3 x 4 matrices over the rationals:

    >> MatGQ := Dom::MatrixGroup(3, 4, Dom::Rational)

                       Dom::MatrixGroup(3, 4, Dom::Rational)

    >> MatGQ::hasProp(Cat::AbelianGroup), MatGQ::hasProp(Cat::Ring)

                                    TRUE, FALSE

`MatGQ` is a commutative group with respect to the addition of matrices. The unit of this group is the 3 x 4 zero matrix:

    >> MatGQ::zero

                                 +-            -+
                                 |  0, 0, 0, 0  |
                                 |              |
                                 |  0, 0, 0, 0  |
                                 |              |
                                 |  0, 0, 0, 0  |
                                 +-            -+

Note that some operations defined by the domain `MatGQ` return matrices which are no longer elements of the matrix group. They return matrices of the domain `Dom::Matrix(Dom::Rational)`, the super-domain of `MatGQ`.

For example, if we define the matrix:

    >> A := MatGQ([[1, 2, 1, 2], [-5, 3], [2, 1/3, 0, 1]])

                                +-               -+
                                |   1,  2,  1, 2  |
                                |                 |
                                |  -5,  3,  0, 0  |
                                |                 |
                                |   2, 1/3, 0, 1  |
                                +-               -+

and delete its third column, we get the matrix:

    >> MatGQ::delCol(A, 3)

                                 +-            -+
                                 |   1,  2,  2  |
                                 |              |
                                 |  -5,  3,  0  |
                                 |              |
                                 |   2, 1/3, 1  |
                                 +-            -+

which is of the domain type:

    >> domtype(%)

                            Dom::Matrix(Dom::Rational)

As another example we create the 3 x 3 identity matrix using the method `"identity"` of our domain:

    >> E3 := MatGQ::identity(3)

                                   +-         -+
                                   |  1, 0, 0  |
                                   |           |
                                   |  0, 1, 0  |
                                   |           |
                                   |  0, 0, 1  |
                                   +-         -+

This is also a matrix of the domain `Dom::Matrix(Dom::Rational)`:

    >> domtype(E3)

                            Dom::Matrix(Dom::Rational)

If we concatenate `E3` to the right of the matrix `A` defined above, we get the 3 x 7 matrix:

    >> B := A . E3

                           +-                        -+
                           |   1,  2,  1, 2, 1, 0, 0  |
                           |                          |
                           |  -5,  3,  0, 0, 0, 1, 0  |
                           |                          |
                           |   2, 1/3, 0, 1, 0, 0, 1  |
                           +-                        -+

which is of the domain type `Dom::Matrix(Dom::Rational)`:

    >> domtype(B)

                            Dom::Matrix(Dom::Rational)

#### Example 2

We can convert a matrix from a domain created with `Dom::MatrixGroup` into or from another matrix domain, as shown next:

    >> MatGR := Dom::MatrixGroup(2, 3, Dom::Real):
       MatC := Dom::Matrix(Dom::Complex):

    >> A := MatGR((i, j) -> i*j)

                                   +-         -+
                                   |  1, 2, 3  |
                                   |           |
                                   |  2, 4, 6  |
                                   +-         -+

To convert `A` into a matrix of the domain `MatC`, enter:

    >> coerce(A, MatC)

                                   +-         -+
                                   |  1, 2, 3  |
                                   |           |
                                   |  2, 4, 6  |
                                   +-         -+

    >> domtype(%)

                             Dom::Matrix(Dom::Complex)

The conversion is done component-wise. For example, we define the following matrix:

    >> B := MatC([[0, 1, 0], [exp(I), 0, 1]])

                                +-              -+
                                |     0,   1, 0  |
                                |                |
                                |  exp(I), 0, 1  |
                                +-              -+

The matrix B has one complex component and therefore cannot be converted into the domain `MatGR`:

    >> coerce(B, MatGR)

                                       FAIL

Note: The system function `coerce` uses the methods `"convert"` and `"convert_to"` implemented by any domain created with `Dom::MatrixGroup` and `Dom::Matrix`.

#### Super-Domain

`Dom::Matrix`

#### Axioms

if `R` has `Ax::canonicalRep`, then
`Ax::canonicalRep`

#### Changes

- new function

- The method `"dimen"` was renamed to `"matdim"`.
- The method `"newThis"` was renamed to `"create"`.
- Some new methods were implemented or extended for the domain `Dom::Matrix`. See the corresponding help page for details. Note that `Dom::MatrixGroup``(m, n, R)` inherits every method which is defined for `Dom::Matrix(R)` and not re-implemented by `Dom::MatrixGroup``(m, n, R)`.

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000