## `Dom::SquareMatrix` -- the rings of square matrices

#### Introduction

`Dom::SquareMatrix``(n, R)` creates the ring of n x n matrices over the component ring R.

#### Domain

`Dom::SquareMatrix(n <, R>)`

#### Parameters

`n` | - | a positive integer
`R` | - | a ring, i.e., a domain of category `Cat::Rng`; default is `Dom::ExpressionField()`

#### Details

- `Dom::SquareMatrix``(n, R)` creates a domain which represents the ring of n x n matrices over a component domain `R`. The domain `R` must be of category `Cat::Rng` (a ring, possibly without unit).
- If the optional parameter `R` is not given, the domain `Dom::ExpressionField()` is used as the component ring for the square matrices.
- For matrices of a domain created by `Dom::SquareMatrix``(n, R)`, standard matrix arithmetic is implemented by overloading the standard arithmetical operators `+, -, *, /` and `^`. All functions of the `linalg` package dealing with matrices can also be applied.
- `Dom::SquareMatrix``(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::SquareMatrix``(n, R)`.

  Methods described below are re-implemented by `Dom::SquareMatrix`.

- 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::MatrixGroup(m, n, R)` represents the Abelian group of m x n matrices over R.

#### Creating Elements

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

#### Parameters

`Array` | - | an `n` x `n` array
`Matrix` | - | an `n` 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 `n` 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::SquareMatrix(R)`

#### Related Domains

`Dom::Matrix`, `Dom::MatrixGroup`

#### Details

- `Dom::SquareMatrix``(n, R)(Array)` and `Dom::SquareMatrix``(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::SquareMatrix``(n, R)( <n, n>)` returns the n x n zero matrix. Note that the n x n zero matrix is also defined by the entry `"zero"` (see below).
- `Dom::SquareMatrix``(n, R)( <n, n, >ListOfRows)` creates an n 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 `n` inner lists, the remaining lower rows of the matrix are filled with zeroes.

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

- `Dom::SquareMatrix``(n, R)( <n, n, >f)` returns the matrix whose (i,j)th component is the value of the function call `f(i, j)`. The row and column indices i and j range from 1 to `n`.

  The function values are converted 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::SquareMatrix``(n, R)( <n, n, >List, Diagonal)` creates the n x n diagonal matrix whose diagonal elements are the entries of `List`.

  `List` must have at most `n` entries. If it has fewer elements, the remaining diagonal elements 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.

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

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

#### Option: Banded

- `Dom::SquareMatrix``(n, R)( <n, n, >List, Banded)` creates an n 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 the n x n identity matrix. This entry exists if the component ring `R` is a domain of category `Cat::Ring`, i.e., a ring with unit.

randomDimen

  is set to `[n, n]`.

zero

  is the n 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::SquareMatrix``(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 `k`<>`n`.

  - This method only exists if the component ring `R` is of category `Cat::Ring`, i.e., a ring with unit.

#### Method matdim: matrix dimension

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

#### Method random: random matrix generation

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

#### Method _concat: horizontal 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 matrix returned 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`.
- `_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 returned is of the domain `Dom::Matrix(R)`!

  - This method overloads the function `_index` for matrices, i.e., one may use it in the form `A[i, j]` and `A[r1..r2, c1..c2]`, respectively or in functional notation: `_index(A...)`.

#### Method concatMatrix: horizontal 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 type `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 matrix returned 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 matrix returned is of the domain `Dom::Matrix(R)`.

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

#### 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 the domain `Dom::Matrix(R)`.
  - An error message is issued if `r` is less than one or greater than `n`.

#### Method stackMatrix: vertical concatenation of matrices

- `stackMatrix(dom A, dom B...)`
- - This method stacks the matrix `A` on top of the matrix `B`. If further arguments are given, 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 create: defining matrices without component conversions

- `create(any x...)`
- - This method creates a new matrix assuming that the components are of domain type `R`.

    See ``Creating Elements'' above for a complete description of the parameters, with one exception: one cannot use this method to create a matrix from a function or a functional expression.

  - This method should be used if the elements of the parameters `x`... are elements of the domain type `R`. This is often the case if a matrix is to be created whose components come from preceding matrix and scalar operations.

#### 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::SquareMatrix`.

These examples only concentrate on some differences with respect to working with matrices of the domain `Dom::Matrix(R)`.

The following command defines the ring of two-dimensional matrices over the rationals:

    >> SqMatQ := Dom::SquareMatrix(2, Dom::Rational)

                        Dom::SquareMatrix(2, Dom::Rational)

    >> SqMatQ::hasProp(Cat::Ring)

                                       TRUE

The unit is defined by the entry `"one"`, which is the 2 x 2 identity matrix:

    >> SqMatQ::one

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

Note that some operations defined by the domain `SqMatQ` return matrices which are no longer square. They return therefore matrices of the domain `Dom::Matrix(Dom::Rational)`, the super-domain of `SqMatQ`. For example, if we delete the first row of the matrix:

    >> A := SqMatQ([[1, 2], [-5, 3]])

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

we get the matrix:

    >> SqMatQ::delRow(A, 1)

                                     +-     -+
                                     | -5, 3 |
                                     +-     -+

which is of the domain type:

    >> domtype(%)

                            Dom::Matrix(Dom::Rational)

#### Example 2

We can convert a square matrix into or from another matrix domain, as shown next:

    >> SqMatR := Dom::SquareMatrix(3, Dom::Real):
       MatC := Dom::Matrix(Dom::Complex):

    >> A := SqMatR((i, j) -> sin(i*j))

                           +-                        -+
                           |  sin(1), sin(2), sin(3)  |
                           |                          |
                           |  sin(2), sin(4), sin(6)  |
                           |                          |
                           |  sin(3), sin(6), sin(9)  |
                           +-                        -+

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

    >> coerce(A, MatC)

                           +-                        -+
                           |  sin(1), sin(2), sin(3)  |
                           |                          |
                           |  sin(2), sin(4), sin(6)  |
                           |                          |
                           |  sin(3), sin(6), sin(9)  |
                           +-                        -+

    >> domtype(%)

                             Dom::Matrix(Dom::Complex)

The conversion is done component-wise, as the following examples shows:

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

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

The matrix B is square but has one complex component and therefore cannot be converted into the domain `SqMatR`:

    >> coerce(B, SqMatR)

                                       FAIL

#### Super-Domain

`Dom::Matrix`

#### Axioms

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

#### Changes

- 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::SquareMatrix``(n, R)` inherits every method which is defined for `Dom::Matrix(R)` and not re-implemented by `Dom::SquareMatrix``(n, R)`.

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