Vector and Matrix Objects This chapter describes an interface to vector and matrix objects which are not represented by plain lists (of plain lists), cf. Chapters and .
Concepts and Rules for Vector and Matrix Objects <#Include Label="MatObj_Overview">
Categories of Vector and Matrix Objects Currently the following categories of vector and matrix objects are supported in &GAP;. More can be added as soon as there is need for them. <#Include Label="IsVectorObj"> <#Include Label="IsMatrixObj"> <#Include Label="IsMatrixOrMatrixObj"> <#Include Label="IsRowListMatrix">
Defining Attributes of Vector and Matrix Objects <#Include Label="BaseDomain"> <#Include Label="ConstructingFilter"> <#Include Label="CompatibleVectorFilter"> <#Include Label="Length_IsVectorObj"> <#Include Label="NumberRowsNumberColumns">
Constructing Vector and Matrix Objects <#Include Label="NewVector"> <#Include Label="Vector"> <#Include Label="VectorObj_ZeroVector"> <#Include Label="NewMatrix"> <#Include Label="MatObj_Matrix"> <#Include Label="MatObj_ZeroMatrix"> <#Include Label="MatObj_IdentityMatrix">
Operations for Base Domains of Vector and Matrix Objects <#Include Label="OneOfBaseDomain">
Operations for Vector and Matrix Objects <#Include Label="MatrixObjCompare"> <#Include Label="Unpack"> <#Include Label="ChangedBaseDomain"> <#Include Label="Randomize">
List Like Operations for Vector Objects The following operations that are defined for lists are useful also for vector objects. (More such operations can be added if this is appropriate.) <#Include Label="ElementAccessVectorObj"> <#Include Label="MatObj_PositionNonZero"> <#Include Label="MatObj_PositionLastNonZero"> <#Include Label="MatObj_ListOp">
Arithmetical Operations for Vector Objects <#Include Label="VectorObj_UnaryArithmetics"> <#Include Label="VectorObj_BinaryArithmetics"> <#Include Label="MatObj_AddVector"> <#Include Label="MatObj_MultVectorLeft">
Operations for Vector Objects <#Include Label="MatObj_ConcatenationOfVectors"> <#Include Label="MatObj_ExtractSubVector"> <#Include Label="CopySubVector"> <#Include Label="MatObj_WeightOfVector"> <#Include Label="MatObj_DistanceOfVectors">
Arithmetical Operations for Matrix Objects <#Include Label="MatrixObj_UnaryArithmetics"> <#Include Label="MatrixObj_BinaryArithmetics">
Operations for Matrix Objects <#Include Label="MatObj_MatElm"> <#Include Label="MatObj_SetMatElm"> <#Include Label="ExtractSubMatrix"> <#Include Label="MutableCopyMatrix"> <#Include Label="CopySubMatrix"> <#Include Label="CompatibleVector"> <#Include Label="RowsOfMatrix"> <#Include Label="MatObj_CompanionMatrix">
Operations for Row List Matrix Objects In general, matrix objects are not lists in the sense of , and they need not behave like lists, that is, they need not obey all the rules for lists that are stated in Chapter . There are situations where one wants to have matrix objects that can on the one hand benefit from &GAP;'s method selection, as is explained in Section , and do on the other hands support access to &GAP; objects that represent their rows (which are suitable vector objects). Matrix objects whose value implies support the operations described in this section.

One implementation of such matrices is given by the value , and any row of these matrices is a vector object in . Note that these objects do not lie in (and in particular not in ), thus we are allowed to define the above operations only restrictively, as follows.

Unbinding an entry in a row or unbinding a row in a matrix is allowed only in the last position, that is, the vector and matrix objects insist on being dense. All rows of a matrix must have the same length and the same base domain. <#Include Label="RowListMatObj_[]"> <#Include Label="RowListMatObj_[]_ASS"> <#Include Label="RowListMatObj_{}"> <#Include Label="RowListMatObj_{}_ASS"> <#Include Label="RowListMatObj_IsBound"> <#Include Label="RowListMatObj_Unbind"> <#Include Label="RowListMatObj_Add"> <#Include Label="RowListMatObj_Remove"> <#Include Label="RowListMatObj_Append"> <#Include Label="RowListMatObj_ShallowCopy"> <#Include Label="RowListMatObj_ListOp">
Basic operations for row/column reductions <#Include Label="MultMatrixRow"> <#Include Label="MultMatrixRowRight"> <#Include Label="MultMatrixColumn"> <#Include Label="MultMatrixColumnLeft"> <#Include Label="AddMatrixRows"> <#Include Label="AddMatrixRowsRight"> <#Include Label="AddMatrixColumns"> <#Include Label="AddMatrixColumnsLeft"> <#Include Label="PositionNonZeroInRow"> <#Include Label="SwapMatrixRows"> <#Include Label="SwapMatrixColumns"> <#Include Label="AddMatrix"> <#Include Label="MultMatrix">
Implementing New Vector and Matrix Objects Types The first step in the design of a new type of vector or matrix objects is to create a new filter that serves as the of the new objects, see the sections and for an overview of such filters that are already available.

Here we list those operations for vector and matrix objects for which no default methods can be installed. When one implements a new type of vector or matrix objects then one has to install specific methods at least for these operations, in order to make the objects behave as described in this chapter. It is advisable to install specific methods also for other operations, for performance reasons. The installations of default methods can be found in the file lib/matobj.gi of the &GAP; distribution. There one can check for which operations it makes sense to overload them for the new type of vector or matrix objects. Note that the specific methods must be installed with whenever the default method is installed with this function.

Vector objects , , , (with consistency checks if the global option check is not set to false), (see ), , (with consistency checks if the global option check is not set to false, install the method with ).

Matrix objects , , , , (with consistency checks if the global option check is not set to false), (see ), , , (with consistency checks if the global option check is not set to false, install the method with ).

Methods for and must check their arguments for consistency (do the given filter and base domain fit together, are the entries compatible with the given base domain, is the number of matrix entries a multiple of the given number of columns) except if the global option check is set to false. (See Chapter for information about global options.) The same holds for methods for operations that modify mutable vector or matrix objects, such as , , , , and for those methods of and that do not delegate to and , respectively.
Available Representations of Vector Objects The following filters define vector objects for which the the functionality described in this chapter is supported. <#Include Label="IsGF2VectorRep"> <#Include Label="Is8BitVectorRep"> <#Include Label="IsPlistVectorRep"> <#Include Label="IsZmodnZVectorRep">
Available Representations of Matrix Objects The following filters define matrix objects for which the the functionality described in this chapter is supported. <#Include Label="IsGF2MatrixRep"> <#Include Label="Is8BitMatrixRep"> <#Include Label="IsPlistMatrixRep"> <#Include Label="IsGenericMatrixRep"> <#Include Label="IsZmodnZMatrixRep">
Groups Consisting of Matrix Objects One application of matrix objects is to construct groups whose elements are matrix objects. The following conventions hold for such a group G. All elements of G have the same and the same . For a given matrix or matrix object M, a matrix object that can be multiplied with elements of G can be constructed as Matrix( M, Representative( G ) ), and the result can be tested for membership in G. <#Include Label="ConstructingFiltersForMatrixGroupElements">
How to Write Code for Vector and Matrix Objects Vector and matrix objects have a number of different representations in &GAP; which are optimised for different things; see the list for examples of available values of matrix objects. Most &GAP; functions accepting vector or matrix objects as arguments do not depend on any particular representation for these objects. If the output of such a function involves vector and matrix objects, then these are expected to have the same representations as the inputs. For example, a function that computes the Kronecker product of two matrix objects mat1, mat2 may take the two inputs, which must have the same value, create a new matrix object which also lies in this filter, for example by calling ZeroMatrix( m, n, mat1 ), and then set the entries in this matrix.

Functions like , , and admit different kinds of inputs. ZeroMatrix( R, m, n ) can be used, for example, if we want to leave the decision about the representation of the result to &GAP;. This might be useful if the result of ZeroMatrix( R, m, n ) is the first matrix we create, and then later matrices are created relative to this matrix. If we already have a matrix object M and want ZeroMatrix to return a new matrix object that has the same representation as M, then ZeroMatrix( R, m, n ) may not return a matrix with the expected representation. For example, even if we use the same R as before, &GAP; might decide to use a sparse representation for large enough m and n. It is possible to create a ZeroMatrix in the same representation as M by fully specifying this representation as follows ZeroMatrix( ConstructingFilter( M ), BaseDomain( M ), m, n ). It is also possible to produce the same result using the more convenient ZeroMatrix( m, n, M ).

This approach works also in many situation where the input involves the list of list matrices in the filter . In practice, the question is often the other way round: one has old &GAP; code that was written for objects in , and wants to rewrite it such that it works for general matrix objects also. In such cases, the following guidelines may be useful. Use M[i, j] not M[i][j] for accessing/assigning matrix entries.

Reason: M[i][j] means to fetch or even create M[i] and then take the j-th entry of it. Use ExtractSubMatrix( M, rows, cols ) not M{ rows }{ cols } for accessing submatrices, similarly use CopySubMatrix( src, dst, srows, drows, scols, dcols ).

Reason: The M{ rows } syntax is supported only for row-list matrices, see . Use ZeroVector( R, n ) not [ 1 .. n ] * Zero( R ) for creating a zero vector over a given domain R.

Reason: The latter syntax creates an unnecessary new object [ 1 .. n ], multiplies each of its entries with Zero( R ) (not knowing that the result will be Zero( R ) in each case), and creates not a vector object but a plain list of the results. Use ZeroVector( n, M ) not 0 * M[1] for a given matrix object M with n columns.

Reason: Calling M[1] may have to create an unnecessary new object M[1]. Use not .

Reason: This is just a conceptual issue, the results should in fact coincide. A matrix object M which is not a list of lists stores its value. For convenience, DefaultFieldOfMatrix( M ) is defined to return this value (although this need not be a field). On the other hand, a list of lists M in does not store the two attribute values, value is computed from the entries of M, and for convenience, BaseDomain( M ) is defined to return the value. Do not use the unary versions of and .

Reason: For example, consider the two matrices M1 = [ [ Z(4) ] ] and M2 = [ [ Z(4)^3 ] ] over the field with four elements. The latter is in fact a matrix over the field with two elements, and ConvertToMatrixRep( M2 ) turns it into a matrix in , whereas ConvertToMatrixRep( M1 ) yields a matrix in . Thus computing products or sums of these matrices is more expensive than computations with two matrices in . Use and the binary versions of and only when creating initial objects which need not be compatible with given vectors or matrices.

Reason: The idea behind these functions is to choose a good representation for initial data (for example for some expensive MeatAxe computations, see Chapter ). The results of computations with these data should then automatically be in the same representation. If not then the code in question has problems, and adjusting the representation of intermediate results by calling the abovementioned conversion functions just hides these problems. Conversely, do not use functions for vector and matrix objects when you want to create an object that shall be used just as a list. For example, use ListWithIdenticalEntries( n, Zero( R ) ) not Vector( R, n ) in this case. For creating a list with n entries, you can also first call for creating a big enough list, and then enter the values.