## `Dom::SparseMatrixF2` -- the domain of sparse matrices over the field with two elements

#### Introduction

`Dom::SparseMatrixF2` represents the set of all matrices over the finite field with two elements.

#### Domain

`Dom::SparseMatrixF2()`

#### Details

- `Dom::SparseMatrixF2` is mathematically equivalent to `Dom::Matrix``(Dom::IntegerMod(2))`. However, the internal representation guarantees that both storage and computing time required for the arithmetical operations depend on the number of nonzero entries. Therefore, `Dom::SparseMatrixF2` should be used for matrices with few nonzero entries.

#### Introduction

`Dom::SparseMatrixF2``(m, n, [s1, ..., sm])` creates the m times n matrix (aij) such that, for each i, the set of all j with aij=1 equals the set (or list) si.

#### Creating Elements

``Dom::SparseMatrixF2`(m, n, [s1...])`
``Dom::SparseMatrixF2`(m, n, f)`

#### Parameters

`m, n` | - | positive integers
`s1...` | - | sets or lists of integers between 1 and `n`
`f` | - | a procedure or another object that, when called with an integer between 1 and m and another integer between 1 and n, returns an element of `Dom::IntegerMod(2)`.

#### Categories

`Cat::Matrix``(Dom::IntegerMod(2))`

#### Related Domains

`Dom::Matrix`

#### Entries

coeffRing

  The coefficient ring always equals `Dom::IntegerMod(2)`.

isSparse

  This entry is always set to `TRUE`.

#### Method zeroMatrix: matrix of a given dimension, consisting of zeros

- `zeroMatrix(integer m, integer n)`
- - This method returns the m times n matrix whose entries are all zero.

#### Method _plus: add matrices

- `_plus(dom A...)`
- - This method returns the sum of the given matrices. All matrices must have the same dimensions.
  - This method overloads the function `_plus`.

#### Method _negate: negate a matrix

- `_negate(dom A)`
- - Because the coefficient field has characteristic two, the negative of `A` is just `A` itself.
  - This method overloads `_negate`.

#### Method matrixvectorproduct: multiply a matrix and a vector

- `matrixvectorproduct(dom A, dom b)`
- - This method returns the product of the matrix `A` and the column vector `b`; the number of columns of `A` must be the same as the number of rows of `b`.

#### Method _mult: multiply a matrix and a vector

- `_mult(dom A, dom b)`
- - This method does the same as `"matrixvectorproduct"`.
  - It overloads the function `_mult`.

  - The product of arbitrary sparse matrices (where `b` is not a vector) has not been implemented.

#### Method randmatrix: generate random matrix

- `randmatrix(integer m, integer n <integer s>)`
- - This method generates an m times n random matrix by defining in each row s entries to be equal to 1; these are drawn with repetition such that the actual number of ones may be less. If `s` is not given, it defaults to 6.

#### Method nrows: number of rows

- `nrows(dom A)`
- - This method returns the number of rows of `A`.

#### Method ncols: number of rows

- `ncols(dom A)`
- - This method returns the number of columns of `A`.

#### Method dimen: number of rows and columns

- `dimen(dom A)`
- - This method returns a list of two elements, the first being the number of rows, the second being the number of columns of `A`.

#### Method body: body of the matrix

- `body(dom A)`
- - This method returns a list of sets, where the i-th set is the set of the index positions of all ones in the i-th row.

#### Method row: row of a matrix

- `row(dom A, integer i)`
- - This method returns the i-th row of the m times n matrix `A` as a 1 times n matrix of type `Dom::SparseMatrixF2`.

#### Method col: column of a matrix

- `col(dom A, integer i)`
- - This method returns the i-th column of the m times n matrix `A` as a row vector, i.e. as a 1 times m matrix of type `Dom::SparseMatrixF2`.

#### Method _index: row or single entry of a matrix

- `_index(dom A, integer i)`
- - returns the i-th row of `A`.
  - This method overloads the `_index` operator; `A[i]` may be entered equivalently.

- `_index(dom A, integer i, integer j)`
- - returns the entry of `A` in the i-th row, j-th column.
  - Equivalently, `A[i,j]` may be entered.

#### Method set_index: assignment to a matrix entry

- `set_index(dom A, integer i, integer j, value v)`
- - This method returns a copy of `A`, with the result of converting `v` into an element of `Dom::IntegerMod``(2)` entered in the i-th row, j-th column. `Dom::IntegerMod``(2)` must be able to convert `v` into a field element.
  - This method can be used for indexed assignments using the syntax `A[i,j]:=v`. In this case, the value of the identifier or local variable `A` is changed as a side effect; `v` (but not the result of converting it to a field element!) is returned.

    If the assignment stops with an error, the domain element stored in `A` is destroyed, and the new value of `A` is `FAIL`.

  - See `_assign` for more information about indexed assignments.

#### Method convert_to: conversion of a sparse matrix into another type

- `convert_to(dom A, any T)`
- - This method tries to convert `A` into type `T`. Currently only a conversion into a `Dom::Matrix``(Dom::IntegerMod(2))` is possible.

#### Example 1

We create a sparse matrix with three nonzero entries:

    >> A:=Dom::SparseMatrixF2(3, 3, [{2}, {1}, {3}])

                                  [{2}, {1}, {3}]

Conversion to a `Dom::Matrix` yields a nicer output, but now nine entries have to be stored:

    >> A::dom::convert_to(A, Dom::Matrix(Dom::IntegerMod(2)))

                          +-                           -+
                          |  0 mod 2, 1 mod 2, 0 mod 2  |
                          |                             |
                          |  1 mod 2, 0 mod 2, 0 mod 2  |
                          |                             |
                          |  0 mod 2, 0 mod 2, 1 mod 2  |
                          +-                           -+

#### Super-Domain

`Dom::BaseDomain`

#### Axioms

`Ax::canonicalRep`

#### Changes

- new function

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