This section describes the constructs provided for creating sparse matrices.
Given a ring R (optional), integers m, n≥0 and a sequence Q, return the m x n sparse matrix over R whose non-zero entries are those specified by Q, coerced into R. If R is not given, it is derived from the entries in Q. Either of m and n may be 0, in which case Q must have length 0 (and may be null if R is given), and the m x n zero sparse matrix over R is returned. There are two possibilities for Q:
- (a)
- The sequence Q is a sequence of tuples, each of the form <i, j, x>, where 1≤i≤m, 1≤j≤n, and x∈S for some ring S. Such a tuple specifies that the (i, j)-th entry of the matrix is x. If R is given, then x is coerced into R; otherwise the matrix is created over S. If an entry position is not given then its value is zero, while if an entry position is repeated then the last value overrides any previous values.
- (b)
- The sequence Q is a "flat" sequence of integers, giving the entries of the matrix in compact form. To be precise, Q begins with the number of non-zero entries n for the first row, then 2.n integers giving column-entry pairs for the first row, and this format is immediately followed for the second row and so on. A zero row is specified by a zero value for n. If R is given, the integer entries are coerced into R; otherwise the matrix is defined over Z. (Thus this method will not allow elements of R which cannot be created by coercing integers into R alone; another way of saying this is that the entries must all lie in the prime ring of R). This allows a very compact way to create (and store) sparse matrices. The examples below illustrate this format.
Given a ring R, and integers m, n≥0, create the m x n sparse matrix over R.
Given integers m, n≥0, create the m x n sparse matrix over the integer ring Z.
Create the 0 x 0 sparse matrix over R. If R is omitted (so there are no arguments), then R is taken to be the integer ring Z. These functions will usually be called when the user wishes to create a sparse matrix whose final dimensions are initially unknown, and for which the SetEntry procedure below will be used to extend the matrix automatically, as needed.
(a) A sparse 2 x 2 matrix is defined over Z, using the first (sequence of tuples) method. We specify that there is a 3 in the (1, 2) position and a -1 in the (2, 3) position. The ring need not be given since the entries are in Z already.
> A := SparseMatrix(2, 3, [<1,2,3>, <2,3,-1>]); > A; Sparse matrix with 2 rows and 3 columns over Integer Ring > Matrix(A); [ 0 3 0] [ 0 0 -1]
(b) The same matrix is now defined over GF(23). We could also coerce the 3rd component of each tuple into GF(23) and thus omit the first argument.
> A := SparseMatrix(GF(23), 2, 3, [<1,2,3>, <2,3,-1>]); > A; Sparse matrix with 2 rows and 3 columns over GF(23) > Matrix(A); [ 0 3 0] [ 0 0 22]
(c) A similar sparse matrix is defined over GF(24). When A is printed in Magma format, the sequence-of-tuples form is used (because the entries cannot be printed as integers).
> K<w> := GF(2^4);
> A := SparseMatrix(K, 2, 3, [<1,2,3>, <2,3,w>]);
> A;
Sparse matrix with 2 rows and 3 columns over GF(2^4)
> Matrix(A);
[ 0 1 0]
[ 0 0 w]
> A: Magma;
SparseMatrix(GF(2, 4), 2, 3, [
<1, 2, 1>,
<2, 3, w>
])
(d) A sparse 4 x 5 matrix A is defined over Z, using the second (flat integer sequence) method. Here row 1 has one non-zero entry: -1 at column 3; then row 2 has three non-zero entries: 9 at column 2, 7 at column 3, and -3 at column 4; row 3 has no non-zero entries (so we give a 0 at this point); and finally row 4 has one non-zero entry 3 at column 4. Note that when A is printed in Magma format, this time the compact "flat" sequence of integers form is used, since this is possible.
> A := SparseMatrix(4,5, [1,3,-1, 3,2,9,3,7,4,-3, 0, 1,4,3]);
> A;
Sparse matrix with 4 rows and 5 columns over Integer Ring
> Matrix(A);
[ 0 0 -1 0 0]
[ 0 9 7 -3 0]
[ 0 0 0 0 0]
[ 0 0 0 3 0]
> A: Magma;
SparseMatrix(4, 5, \[
1, 3,-1,
3, 2,9, 3,7, 4,-3,
0,
1, 4,3
])
Given a ring R, and an integer n≥0, return the n x n identity sparse matrix over R.
Given an integer n≥0 and an element s of a ring R, return the n x n scalar sparse matrix over R which has s on the diagonal and zeros elsewhere. The argument n may be 0, in which case the 0 x 0 sparse matrix over R is returned.
Given a ring R, an integer n≥0 and an element s of a ring S, return the n x n scalar sparse matrix over R which has s, coerced into R, on the diagonal and zeros elsewhere. n may be 0, in which case in which case the 0 x 0 sparse matrix over R is returned.
Given a ring R, an integer n≥0 and a sequence Q of n ring elements, return the n x n diagonal sparse matrix over R whose diagonal entries correspond to the entries of Q, coerced into R.
Given a ring R and a sequence Q of n ring elements, return the n x n diagonal sparse matrix over R whose diagonal entries correspond to the entries of Q, coerced into R.
Given a sequence Q of n elements from a ring R, return the n x n diagonal sparse matrix over R whose diagonal entries
Given a degree-(2d) permutation g, return the d x d monomial matrix corresponding to g.
Create the structure containing all sparse matrices (of any shape) over ring R. This structure does not need to be created explicitly by the user (it will be the parent of any sparse matrix over R), but it may be useful to create it in this way occasionally.