This chapter is work in progress. It will eventually describe the new interface to vector and matrix objects.
Traditionally, vectors in GAP have been lists and matrices have been lists of lists (of equal length). Unfortunately, such lists cannot store their type and so it is impossible to use the full advantages of GAP's method selection on them. This situation is unsustainable in the long run since more special representations (compressed, sparse, etc.) have already been and even more will be implemented. To eventually solve this problem, this chapter describes a new programming interface to vectors and matrices.
The whole idea of this interface is that vectors and matrices must be proper objects with a stored type (i.e. created by Objectify allowing inheritance) to benefit from method selection. We therefore refer to the new style vectors and matrices as "vector objects" and "matrix objects" respectively.
It should be possible to write (efficient) code that is independent of the actual representation (in the sense of GAP's representation filters) and preserves it.
This latter requirement makes it necessary to distinguish between (at least) two classes of matrices:
"RowList"-Matrices which behave basically like lists of rows, in particular are the rows individual GAP objects that can be shared between different matrix objects.
"Flat" matrices which behave basically like one GAP object that cannot be split up further. In particular a row is only a part of a matrix and no GAP object in itself.
For various reasons these two classes have to be distinguished already with respect to the definition of the operations for them.
In particular vectors and matrices know their BaseDomain and their dimensions. Note that the basic condition is that the elements of vectors and matrices must either lie in the BaseDomain or naturally embed in the sense that + and * and = automatically work with all elements of the base domain (example: integers in polynomials over integers).
Vectors are equal with respect to "=" if they have the same length and the same entries. It is not necessary that they have the same BaseDomain. Matrices are equal with respect to "=" if they have the same dimensions and the same entries. It is possible that not for all pairs of representations methods exist.
It is not guaranteed that all rows of a matrix have the same vector type! It is for example thinkable that a matrix stores some of its rows in a sparse representation and some in a dense one! However, it is guaranteed that the rows of matrices in the same representation are compatible in the sense that all vector operations defined in this interface can be applied to them and that new matrices in the same representation as the original matrix can be formed out of them.
Note that there is neither a default mapping from the set of matrix representations to the set of vector representations nor one in the reverse direction! There is nothing like an "associated" vector representation to a matrix representation or vice versa.
The way to write code that preserves the representation basically works by using constructing operations that take template objects to decide about the actual representation of the new object.
Vectors do not have to be lists in the sense that they do not have to support all list operations. The same holds for matrices. However, RowList matrices behave nearly like lists of row vectors that insist on being dense and containing only vectors of the same length and with the same BaseDomain.
There are some rules embedded in the comments to the following code. They are marked with the word "Rule". FIXME: Collect all rules here.
‣ PositionNonZero( V ) | ( operation ) |
Returns: An integer
Returns the index of the first entry in the vector V which is not zero. If all entries are zero, the function returns Length(V) + 1.
‣ PositionLastNonZero( V ) | ( operation ) |
Returns: An integer
Returns the index of the last entry in the vector V which is not zero. If all entries are zero, the function returns 0.
‣ ListOp( V[, func] ) | ( operation ) |
Returns: A plain list
Applies func to each entry of the vector V and returns the results as a plain list. This allows for calling List (30.3-5) on vectors. If the argument func is not provided, applies IdFunc (5.4-6) to all entries.
‣ Unpack( V ) | ( operation ) |
Returns: A plain list
Returns a new plain list containing the entries of V. Guarantees to return a new list which can be manipulated without changing V. The entries itself are not copied.
‣ ConcatenationOfVectors( V1, V2, ... ) | ( function ) |
‣ ConcatenationOfVectors( Vlist ) | ( function ) |
Returns: a vector object
Returns a new vector containing the entries of V1, V2, etc. As prototype V1 is used.
‣ ExtractSubVector( V, l ) | ( operation ) |
Returns: a vector object
Returns a new vector containing the entries of V at the positions in l.
‣ ZeroVector( l, V ) | ( operation ) |
Returns: a vector object
Returns a new vector of length l in the same representation as V containing only zeros.
‣ ConstructingFilter( V ) | ( operation ) |
Returns: a filter
Returns a filter f such that if NewVector is called with f a vector in the same representation as V is produced.
‣ Randomize( [Rs, ]v ) | ( operation ) |
‣ Randomize( [Rs, ]m ) | ( operation ) |
Replaces every entry in the mutable vector object v or matrix object m, respectively, with a random one from the base domain of v or m, respectively, and returns the argument.
If given, the random source Rs is used to compute the random elements. Note that in this case, a Random (14.7-2) method must be available that takes a random source as its first argument and the base domain as its second argument.
‣ WeightOfVector( V ) | ( operation ) |
Returns: an integer
Computes the Hamming weight of the vector V, i.e., the number of nonzero entries.
‣ DistanceOfVectors( V1, V2 ) | ( operation ) |
Returns: an integer
Computes the Hamming distance of the vectors V1 and V2, i.e., the number of entries in which the vectors differ. The vectors must be of equal length.
generated by GAPDoc2HTML