### 61 Vector Spaces

#### 61.1 IsLeftVectorSpace (Filter)

##### 61.1-1 IsLeftVectorSpace
 ‣ IsLeftVectorSpace( V ) ( category )
 ‣ IsVectorSpace( V ) ( category )

A vector space in GAP is a free left module (see IsFreeLeftModule (57.3-1)) over a division ring (see Chapter 58).

Whenever we talk about an $$F$$-vector space V then V is an additive group (see IsAdditiveGroup (55.1-6)) on which the division ring $$F$$ acts via multiplication from the left such that this action and the addition in V are left and right distributive. The division ring $$F$$ can be accessed as value of the attribute LeftActingDomain (57.1-11).

Vector spaces in GAP are always left vector spaces, IsLeftVectorSpace and IsVectorSpace are synonyms.

#### 61.2 Constructing Vector Spaces

##### 61.2-1 VectorSpace
 ‣ VectorSpace( F, gens[, zero][, "basis"] ) ( function )

For a field F and a collection gens of vectors, VectorSpace returns the F-vector space spanned by the elements in gens.

The optional argument zero can be used to specify the zero element of the space; zero must be given if gens is empty. The optional string "basis" indicates that gens is known to be linearly independent over F, in particular the dimension of the vector space is immediately set; note that Basis (61.5-2) need not return the basis formed by gens if the string "basis" is given as an argument.

gap> V:= VectorSpace( Rationals, [ [ 1, 2, 3 ], [ 1, 1, 1 ] ] );
<vector space over Rationals, with 2 generators>


##### 61.2-2 Subspace
 ‣ Subspace( V, gens[, "basis"] ) ( function )
 ‣ SubspaceNC( V, gens[, "basis"] ) ( function )

For an $$F$$-vector space V and a list or collection gens that is a subset of V, Subspace returns the $$F$$-vector space spanned by gens; if gens is empty then the trivial subspace (see TrivialSubspace (61.3-2)) of V is returned. The parent (see 31.7) of the returned vector space is set to V.

SubspaceNC does the same as Subspace, except that it omits the check whether gens is a subset of V.

The optional string "basis" indicates that gens is known to be linearly independent over $$F$$. In this case the dimension of the subspace is immediately set, and both Subspace and SubspaceNC do not check whether gens really is linearly independent and whether gens is a subset of V.

gap> V:= VectorSpace( Rationals, [ [ 1, 2, 3 ], [ 1, 1, 1 ] ] );;
gap> W:= Subspace( V, [ [ 0, 1, 2 ] ] );
<vector space over Rationals, with 1 generators>


##### 61.2-3 AsVectorSpace
 ‣ AsVectorSpace( F, D ) ( operation )

Let F be a division ring and D a domain. If the elements in D form an F-vector space then AsVectorSpace returns this F-vector space, otherwise fail is returned.

AsVectorSpace can be used for example to view a given vector space as a vector space over a smaller or larger division ring.

gap> V:= FullRowSpace( GF( 27 ), 3 );
( GF(3^3)^3 )
gap> Dimension( V );  LeftActingDomain( V );
3
GF(3^3)
gap> W:= AsVectorSpace( GF( 3 ), V );
<vector space over GF(3), with 9 generators>
gap> Dimension( W );  LeftActingDomain( W );
9
GF(3)
gap> AsVectorSpace( GF( 9 ), V );
fail


##### 61.2-4 AsSubspace
 ‣ AsSubspace( V, U ) ( operation )

Let V be an $$F$$-vector space, and U a collection. If U is a subset of V such that the elements of U form an $$F$$-vector space then AsSubspace returns this vector space, with parent set to V (see AsVectorSpace (61.2-3)). Otherwise fail is returned.

gap> V:= VectorSpace( Rationals, [ [ 1, 2, 3 ], [ 1, 1, 1 ] ] );;
gap> W:= VectorSpace( Rationals, [ [ 1/2, 1/2, 1/2 ] ] );;
gap> U:= AsSubspace( V, W );
<vector space over Rationals, with 1 generators>
gap> Parent( U ) = V;
true
gap> AsSubspace( V, [ [ 1, 1, 1 ] ] );
fail


#### 61.3 Operations and Attributes for Vector Spaces

##### 61.3-1 GeneratorsOfLeftVectorSpace
 ‣ GeneratorsOfLeftVectorSpace( V ) ( attribute )
 ‣ GeneratorsOfVectorSpace( V ) ( attribute )

For an $$F$$-vector space V, GeneratorsOfLeftVectorSpace returns a list of vectors in V that generate V as an $$F$$-vector space.

gap> GeneratorsOfVectorSpace( FullRowSpace( Rationals, 3 ) );
[ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ]


##### 61.3-2 TrivialSubspace
 ‣ TrivialSubspace( V ) ( attribute )

For a vector space V, TrivialSubspace returns the subspace of V that consists of the zero vector in V.

gap> V:= GF(3)^3;;
gap> triv:= TrivialSubspace( V );
<vector space of dimension 0 over GF(3)>
gap> AsSet( triv );
[ [ 0*Z(3), 0*Z(3), 0*Z(3) ] ]


#### 61.4 Domains of Subspaces of Vector Spaces

##### 61.4-1 Subspaces
 ‣ Subspaces( V[, k] ) ( attribute )

Called with a finite vector space v, Subspaces returns the domain of all subspaces of V.

Called with V and a nonnegative integer k, Subspaces returns the domain of all k-dimensional subspaces of V.

Special Size (30.4-6) and Iterator (30.8-1) methods are provided for these domains.

##### 61.4-2 IsSubspacesVectorSpace
 ‣ IsSubspacesVectorSpace( D ) ( category )

The domain of all subspaces of a (finite) vector space or of all subspaces of fixed dimension, as returned by Subspaces (61.4-1) (see Subspaces (61.4-1)) lies in the category IsSubspacesVectorSpace.

gap> D:= Subspaces( GF(3)^3 );
Subspaces( ( GF(3)^3 ) )
gap> Size( D );
28
gap> iter:= Iterator( D );;
gap> NextIterator( iter );
<vector space of dimension 0 over GF(3)>
gap> NextIterator( iter );
<vector space of dimension 1 over GF(3)>
gap> IsSubspacesVectorSpace( D );
true


#### 61.5 Bases of Vector Spaces

In GAP, a basis of a free left $$F$$-module $$V$$ is a list of vectors $$B = [ v_1, v_2, \ldots, v_n ]$$ in $$V$$ such that $$V$$ is generated as a left $$F$$-module by these vectors and such that $$B$$ is linearly independent over $$F$$. The integer $$n$$ is the dimension of $$V$$ (see Dimension (57.3-3)). In particular, as each basis is a list (see Chapter 21), it has a length (see Length (21.17-5)), and the $$i$$-th vector of $$B$$ can be accessed as $$B[i]$$.

gap> V:= Rationals^3;
( Rationals^3 )
gap> B:= Basis( V );
CanonicalBasis( ( Rationals^3 ) )
gap> Length( B );
3
gap> B;
[ 1, 0, 0 ]


The operations described below make sense only for bases of finite dimensional vector spaces. (In practice this means that the vector spaces must be low dimensional, that is, the dimension should not exceed a few hundred.)

Besides the basic operations for lists (see 21.2), the basic operations for bases are BasisVectors (61.6-1), Coefficients (61.6-3), LinearCombination (61.6-4), and UnderlyingLeftModule (61.6-2). These and other operations for arbitrary bases are described in 61.6.

For special kinds of bases, further operations are defined (see 61.7).

GAP supports the following three kinds of bases.

Relative bases delegate the work to other bases of the same free left module, via basechange matrices (see RelativeBasis (61.5-4)).

Bases handled by nice bases delegate the work to bases of isomorphic left modules over the same left acting domain (see 61.11).

Finally, of course there must be bases in GAP that really do the work.

For example, in the case of a Gaussian row or matrix space V (see 61.9), Basis( V ) is a semi-echelonized basis (see IsSemiEchelonized (61.9-7)) that uses Gaussian elimination; such a basis is of the third kind. Basis( V, vectors ) is either semi-echelonized or a relative basis. Other examples of bases of the third kind are canonical bases of finite fields and of abelian number fields.

Bases handled by nice bases are described in 61.11. Examples are non-Gaussian row and matrix spaces, and subspaces of finite fields and abelian number fields that are themselves not fields.

##### 61.5-1 IsBasis
 ‣ IsBasis( obj ) ( category )

In GAP, a basis of a free left module is an object that knows how to compute coefficients w.r.t. its basis vectors (see Coefficients (61.6-3)). Bases are constructed by Basis (61.5-2). Each basis is an immutable list, the $$i$$-th entry being the $$i$$-th basis vector.

(See 61.8 for mutable bases.)

gap> V:= GF(2)^2;;
gap> B:= Basis( V );;
gap> IsBasis( B );
true
gap> IsBasis( [ [ 1, 0 ], [ 0, 1 ] ] );
false
gap> IsBasis( Basis( Rationals^2, [ [ 1, 0 ], [ 0, 1 ] ] ) );
true


##### 61.5-2 Basis
 ‣ Basis( V[, vectors] ) ( attribute )
 ‣ BasisNC( V, vectors ) ( operation )

Called with a free left $$F$$-module V as the only argument, Basis returns an $$F$$-basis of V whose vectors are not further specified.

If additionally a list vectors of vectors in V is given that forms an $$F$$-basis of V then Basis returns this basis; if vectors is not linearly independent over $$F$$ or does not generate V as a free left $$F$$-module then fail is returned.

BasisNC does the same as the two argument version of Basis, except that it does not check whether vectors form a basis.

If no basis vectors are prescribed then Basis need not compute basis vectors; in this case, the vectors are computed in the first call to BasisVectors (61.6-1).

gap> V:= VectorSpace( Rationals, [ [ 1, 2, 7 ], [ 1/2, 1/3, 5 ] ] );;
gap> B:= Basis( V );
SemiEchelonBasis( <vector space over Rationals, with
2 generators>, ... )
gap> BasisVectors( B );
[ [ 1, 2, 7 ], [ 0, 1, -9/4 ] ]
gap> B:= Basis( V, [ [ 1, 2, 7 ], [ 3, 2, 30 ] ] );
Basis( <vector space over Rationals, with 2 generators>,
[ [ 1, 2, 7 ], [ 3, 2, 30 ] ] )
gap> Basis( V, [ [ 1, 2, 3 ] ] );
fail


##### 61.5-3 CanonicalBasis
 ‣ CanonicalBasis( V ) ( attribute )

If the vector space V supports a canonical basis then CanonicalBasis returns this basis, otherwise fail is returned.

The defining property of a canonical basis is that its vectors are uniquely determined by the vector space. If canonical bases exist for two vector spaces over the same left acting domain (see LeftActingDomain (57.1-11)) then the equality of these vector spaces can be decided by comparing the canonical bases.

The exact meaning of a canonical basis depends on the type of V. Canonical bases are defined for example for Gaussian row and matrix spaces (see 61.9).

If one designs a new kind of vector spaces (see 61.12) and defines a canonical basis for these spaces then the CanonicalBasis method one installs (see InstallMethod (78.3-1)) must not call Basis (61.5-2). On the other hand, one probably should install a Basis (61.5-2) method that simply calls CanonicalBasis, the value of the method (see 78.3 and 78.4) being CANONICAL_BASIS_FLAGS.

gap> vecs:= [ [ 1, 2, 3 ], [ 1, 1, 1 ], [ 1, 1, 1 ] ];;
gap> V:= VectorSpace( Rationals, vecs );;
gap> B:= CanonicalBasis( V );
CanonicalBasis( <vector space over Rationals, with 3 generators> )
gap> BasisVectors( B );
[ [ 1, 0, -1 ], [ 0, 1, 2 ] ]


##### 61.5-4 RelativeBasis
 ‣ RelativeBasis( B, vectors ) ( operation )
 ‣ RelativeBasisNC( B, vectors ) ( operation )

A relative basis is a basis of the free left module V that delegates the computation of coefficients etc. to another basis of V via a basechange matrix.

Let B be a basis of the free left module V, and vectors a list of vectors in V.

RelativeBasis checks whether vectors form a basis of V, and in this case a basis is returned in which vectors are the basis vectors; otherwise fail is returned.

RelativeBasisNC does the same, except that it omits the check.

#### 61.6 Operations for Vector Space Bases

##### 61.6-1 BasisVectors
 ‣ BasisVectors( B ) ( attribute )

For a vector space basis B, BasisVectors returns the list of basis vectors of B. The lists B and BasisVectors( B ) are equal; the main purpose of BasisVectors is to provide access to a list of vectors that does not know about an underlying vector space.

gap> V:= VectorSpace( Rationals, [ [ 1, 2, 7 ], [ 1/2, 1/3, 5 ] ] );;
gap> B:= Basis( V, [ [ 1, 2, 7 ], [ 0, 1, -9/4 ] ] );;
gap> BasisVectors( B );
[ [ 1, 2, 7 ], [ 0, 1, -9/4 ] ]


##### 61.6-2 UnderlyingLeftModule
 ‣ UnderlyingLeftModule( B ) ( attribute )

For a basis B of a free left module $$V$$, say, UnderlyingLeftModule returns $$V$$.

The reason why a basis stores a free left module is that otherwise one would have to store the basis vectors and the coefficient domain separately. Storing the module allows one for example to deal with bases whose basis vectors have not yet been computed yet (see Basis (61.5-2)); furthermore, in some cases it is convenient to test membership of a vector in the module before computing coefficients w.r.t. a basis.

gap> B:= Basis( GF(2)^6 );;  UnderlyingLeftModule( B );
( GF(2)^6 )


##### 61.6-3 Coefficients
 ‣ Coefficients( B, v ) ( operation )

Let $$V$$ be the underlying left module of the basis B, and v a vector such that the family of v is the elements family of the family of $$V$$. Then Coefficients( B, v ) is the list of coefficients of v w.r.t. B if v lies in $$V$$, and fail otherwise.

gap> V:= VectorSpace( Rationals, [ [ 1, 2, 7 ], [ 1/2, 1/3, 5 ] ] );;
gap> B:= Basis( V, [ [ 1, 2, 7 ], [ 0, 1, -9/4 ] ] );;
gap> Coefficients( B, [ 1/2, 1/3, 5 ] );
[ 1/2, -2/3 ]
gap> Coefficients( B, [ 1, 0, 0 ] );
fail


##### 61.6-4 LinearCombination
 ‣ LinearCombination( B, coeff ) ( operation )

If B is a basis object (see IsBasis (61.5-1)) or a homogeneous list of length $$n$$, say, and coeff is a row vector of the same length, LinearCombination returns the vector $$\sum_{{i = 1}}^n \textit{coeff}[i] * \textit{B}[i]$$.

Perhaps the most important usage is the case where B forms a basis.

gap> V:= VectorSpace( Rationals, [ [ 1, 2, 7 ], [ 1/2, 1/3, 5 ] ] );;
gap> B:= Basis( V, [ [ 1, 2, 7 ], [ 0, 1, -9/4 ] ] );;
gap> LinearCombination( B, [ 1/2, -2/3 ] );
[ 1/2, 1/3, 5 ]


##### 61.6-5 EnumeratorByBasis
 ‣ EnumeratorByBasis( B ) ( attribute )

For a basis B of the free left $$F$$-module $$V$$ of dimension $$n$$, say, EnumeratorByBasis returns an enumerator that loops over the elements of $$V$$ as linear combinations of the vectors of B with coefficients the row vectors in the full row space (see FullRowSpace (61.9-4)) of dimension $$n$$ over $$F$$, in the succession given by the default enumerator of this row space.

gap> V:= GF(2)^3;;
gap> enum:= EnumeratorByBasis( CanonicalBasis( V ) );;
gap> Print( enum{ [ 1 .. 4 ] }, "\n" );
[ [ 0*Z(2), 0*Z(2), 0*Z(2) ], [ 0*Z(2), 0*Z(2), Z(2)^0 ],
[ 0*Z(2), Z(2)^0, 0*Z(2) ], [ 0*Z(2), Z(2)^0, Z(2)^0 ] ]
gap> B:= Basis( V, [ [ 1, 1, 1 ], [ 1, 1, 0 ], [ 1, 0, 0 ] ] * Z(2) );;
gap> enum:= EnumeratorByBasis( B );;
gap> Print( enum{ [ 1 .. 4 ] }, "\n" );
[ [ 0*Z(2), 0*Z(2), 0*Z(2) ], [ Z(2)^0, 0*Z(2), 0*Z(2) ],
[ Z(2)^0, Z(2)^0, 0*Z(2) ], [ 0*Z(2), Z(2)^0, 0*Z(2) ] ]


##### 61.6-6 IteratorByBasis
 ‣ IteratorByBasis( B ) ( operation )

For a basis B of the free left $$F$$-module $$V$$ of dimension $$n$$, say, IteratorByBasis returns an iterator that loops over the elements of $$V$$ as linear combinations of the vectors of B with coefficients the row vectors in the full row space (see FullRowSpace (61.9-4)) of dimension $$n$$ over $$F$$, in the succession given by the default enumerator of this row space.

gap> V:= GF(2)^3;;
gap> iter:= IteratorByBasis( CanonicalBasis( V ) );;
gap> for i in [ 1 .. 4 ] do Print( NextIterator( iter ), "\n" ); od;
[ 0*Z(2), 0*Z(2), 0*Z(2) ]
[ 0*Z(2), 0*Z(2), Z(2)^0 ]
[ 0*Z(2), Z(2)^0, 0*Z(2) ]
[ 0*Z(2), Z(2)^0, Z(2)^0 ]
gap> B:= Basis( V, [ [ 1, 1, 1 ], [ 1, 1, 0 ], [ 1, 0, 0 ] ] * Z(2) );;
gap> iter:= IteratorByBasis( B );;
gap> for i in [ 1 .. 4 ] do Print( NextIterator( iter ), "\n" ); od;
[ 0*Z(2), 0*Z(2), 0*Z(2) ]
[ Z(2)^0, 0*Z(2), 0*Z(2) ]
[ Z(2)^0, Z(2)^0, 0*Z(2) ]
[ 0*Z(2), Z(2)^0, 0*Z(2) ]


#### 61.7 Operations for Special Kinds of Bases

##### 61.7-1 IsCanonicalBasis
 ‣ IsCanonicalBasis( B ) ( property )

If the underlying free left module $$V$$ of the basis B supports a canonical basis (see CanonicalBasis (61.5-3)) then IsCanonicalBasis returns true if B is equal to the canonical basis of $$V$$, and false otherwise.

##### 61.7-2 IsIntegralBasis
 ‣ IsIntegralBasis( B ) ( property )

Let B be an $$S$$-basis of a field $$F$$, say, for a subfield $$S$$ of $$F$$, and let $$R$$ and $$M$$ be the rings of algebraic integers in $$S$$ and $$F$$, respectively. IsIntegralBasis returns true if B is also an $$R$$-basis of $$M$$, and false otherwise.

##### 61.7-3 IsNormalBasis
 ‣ IsNormalBasis( B ) ( property )

Let B be an $$S$$-basis of a field $$F$$, say, for a subfield $$S$$ of $$F$$. IsNormalBasis returns true if B is invariant under the Galois group (see GaloisGroup (58.3-1)) of the field extension $$F / S$$, and false otherwise.

gap> B:= CanonicalBasis( GaussianRationals );
CanonicalBasis( GaussianRationals )
gap> IsIntegralBasis( B );  IsNormalBasis( B );
true
false


#### 61.8 Mutable Bases

It is useful to have a mutable basis of a free module when successively closures with new vectors are formed, since one does not want to create a new module and a corresponding basis for each step.

Note that the situation here is different from the situation with stabilizer chains, which are (mutable or immutable) records that do not need to know about the groups they describe, whereas each (immutable) basis stores the underlying left module (see UnderlyingLeftModule (61.6-2)).

So immutable bases and mutable bases are different categories of objects. The only thing they have in common is that one can ask both for their basis vectors and for the coefficients of a given vector.

Since Immutable produces an immutable copy of any GAP object, it would in principle be possible to construct a mutable basis that is in fact immutable. In the sequel, we will deal only with mutable bases that are in fact mutable GAP objects, hence these objects are unable to store attribute values.

Basic operations for immutable bases are NrBasisVectors (61.8-3), IsContainedInSpan (61.8-5), CloseMutableBasis (61.8-6), ImmutableBasis (61.8-4), Coefficients (61.6-3), and BasisVectors (61.6-1). ShallowCopy (12.7-1) for a mutable basis returns a mutable plain list containing the current basis vectors.

Since mutable bases do not admit arbitrary changes of their lists of basis vectors, a mutable basis is not a list. It is, however, a collection, more precisely its family (see 13.1) equals the family of its collection of basis vectors.

Mutable bases can be constructed with MutableBasis.

Similar to the situation with bases (cf. 61.5), GAP supports the following three kinds of mutable bases.

The generic method of MutableBasis returns a mutable basis that simply stores an immutable basis; clearly one wants to avoid this whenever possible with reasonable effort.

There are mutable bases that store a mutable basis for a nicer module. Note that this is meaningful only if the mechanism of computing nice and ugly vectors (see 61.11) is invariant under closures of the basis; this is the case for example if the vectors are matrices, Lie objects, or elements of structure constants algebras.

There are mutable bases that use special information to perform their tasks; examples are mutable bases of Gaussian row and matrix spaces.

##### 61.8-1 IsMutableBasis
 ‣ IsMutableBasis( MB ) ( category )

Every mutable basis lies in the category IsMutableBasis.

##### 61.8-2 MutableBasis
 ‣ MutableBasis( R, vectors[, zero] ) ( operation )

MutableBasis returns a mutable basis for the R-free module generated by the vectors in the list vectors. The optional argument zero is the zero vector of the module; it must be given if vectors is empty.

Note that vectors will in general not be the basis vectors of the mutable basis!

gap> MB:= MutableBasis( Rationals, [ [ 1, 2, 3 ], [ 0, 1, 0 ] ] );
<mutable basis over Rationals, 2 vectors>


##### 61.8-3 NrBasisVectors
 ‣ NrBasisVectors( MB ) ( operation )

For a mutable basis MB, NrBasisVectors returns the current number of basis vectors of MB. Note that this operation is not an attribute, as it makes no sense to store the value. NrBasisVectors is used mainly as an equivalent of Dimension for the underlying left module in the case of immutable bases.

gap> MB:= MutableBasis( Rationals, [ [ 1, 1], [ 2, 2 ] ] );;
gap> NrBasisVectors( MB );
1


##### 61.8-4 ImmutableBasis
 ‣ ImmutableBasis( MB[, V] ) ( operation )

ImmutableBasis returns the immutable basis $$B$$, say, with the same basis vectors as in the mutable basis MB.

If the second argument V is present then V is the value of UnderlyingLeftModule (61.6-2) for $$B$$. The second variant is used mainly for the case that one knows the module for the desired basis in advance, and if it has a nicer structure than the module known to MB, for example if it is an algebra.

gap> MB:= MutableBasis( Rationals, [ [ 1, 1 ], [ 2, 2 ] ] );;
gap> B:= ImmutableBasis( MB );
SemiEchelonBasis( <vector space of dimension 1 over Rationals>,
[ [ 1, 1 ] ] )
gap> UnderlyingLeftModule( B );
<vector space of dimension 1 over Rationals>


##### 61.8-5 IsContainedInSpan
 ‣ IsContainedInSpan( MB, v ) ( operation )

For a mutable basis MB over the coefficient ring $$R$$, say, and a vector v, IsContainedInSpan returns true is v lies in the $$R$$-span of the current basis vectors of MB, and false otherwise.

##### 61.8-6 CloseMutableBasis
 ‣ CloseMutableBasis( MB, v ) ( operation )

For a mutable basis MB over the coefficient ring $$R$$, say, and a vector v, CloseMutableBasis changes MB such that afterwards it describes the $$R$$-span of the former basis vectors together with v.

Note that if v enlarges the dimension then this does in general not mean that v is simply added to the basis vectors of MB. Usually a linear combination of v and the other basis vectors is added, and also the old basis vectors may be modified, for example in order to keep the list of basis vectors echelonized (see IsSemiEchelonized (61.9-7)).

CloseMutableBasis returns false if v was already in the $$R$$-span described by MB, and true if MB got extended.

gap> MB:= MutableBasis( Rationals, [ [ 1, 1, 3 ], [ 2, 2, 1 ] ] );
<mutable basis over Rationals, 2 vectors>
gap> IsContainedInSpan( MB, [ 1, 0, 0 ] );
false
gap> CloseMutableBasis( MB, [ 1, 0, 0 ] );
true
gap> MB;
<mutable basis over Rationals, 3 vectors>
gap> IsContainedInSpan( MB, [ 1, 0, 0 ] );
true
gap> CloseMutableBasis( MB, [ 1, 0, 0 ] );
false


#### 61.9 Row and Matrix Spaces

##### 61.9-1 IsRowSpace
 ‣ IsRowSpace( V ) ( filter )

A row space in GAP is a vector space that consists of row vectors (see Chapter 23).

##### 61.9-2 IsMatrixSpace
 ‣ IsMatrixSpace( V ) ( filter )

A matrix space in GAP is a vector space that consists of matrices (see Chapter 24).

##### 61.9-3 IsGaussianSpace
 ‣ IsGaussianSpace( V ) ( filter )

The filter IsGaussianSpace (see 13.2) for the row space (see IsRowSpace (61.9-1)) or matrix space (see IsMatrixSpace (61.9-2)) V over the field $$F$$, say, indicates that the entries of all row vectors or matrices in V, respectively, are all contained in $$F$$. In this case, V is called a Gaussian vector space. Bases for Gaussian spaces can be computed using Gaussian elimination for a given list of vector space generators.

gap> mats:= [ [[1,1],[2,2]], [[3,4],[0,1]] ];;
gap> V:= VectorSpace( Rationals, mats );;
gap> IsGaussianSpace( V );
true
gap> mats:= E(4);;   # an element in an extension field
gap> V:= VectorSpace( Rationals, mats );;
gap> IsGaussianSpace( V );
false
gap> V:= VectorSpace( Field( Rationals, [ E(4) ] ), mats );;
gap> IsGaussianSpace( V );
true


##### 61.9-4 FullRowSpace
 ‣ FullRowSpace( F, n ) ( function )
 ‣ \^( F, n ) ( method )

For a field F and a nonnegative integer n, FullRowSpace returns the F-vector space that consists of all row vectors (see IsRowVector (23.1-1)) of length n with entries in F.

An alternative to construct this vector space is via F^n.

gap> FullRowSpace( GF( 9 ), 3 );
( GF(3^2)^3 )
gap> GF(9)^3;           # the same as above
( GF(3^2)^3 )


##### 61.9-5 FullMatrixSpace
 ‣ FullMatrixSpace( F, m, n ) ( function )
 ‣ \^( F, dims ) ( method )

For a field F and two positive integers m and n, FullMatrixSpace returns the F-vector space that consists of all m by n matrices (see IsMatrix (24.2-1)) with entries in F.

If m = n then the result is in fact an algebra (see FullMatrixAlgebra (62.5-4)).

An alternative to construct this vector space is via F^[m,n].

gap> FullMatrixSpace( GF(2), 4, 5 );
( GF(2)^[ 4, 5 ] )
gap> GF(2)^[ 4, 5 ];    # the same as above
( GF(2)^[ 4, 5 ] )


##### 61.9-6 DimensionOfVectors
 ‣ DimensionOfVectors( M ) ( attribute )

For a left module M that consists of row vectors (see IsRowModule (57.3-6)), DimensionOfVectors returns the common length of all row vectors in M. For a left module M that consists of matrices (see IsMatrixModule (57.3-7)), DimensionOfVectors returns the common matrix dimensions (see DimensionsMat (24.4-1)) of all matrices in M.

gap> DimensionOfVectors( GF(2)^5 );
5
gap> DimensionOfVectors( GF(2)^[2,3] );
[ 2, 3 ]


##### 61.9-7 IsSemiEchelonized
 ‣ IsSemiEchelonized( B ) ( property )

Let B be a basis of a Gaussian row or matrix space $$V$$, say (see IsGaussianSpace (61.9-3)) over the field $$F$$.

If $$V$$ is a row space then B is semi-echelonized if the matrix formed by its basis vectors has the property that the first nonzero element in each row is the identity of $$F$$, and all values exactly below these pivot elements are the zero of $$F$$ (cf. SemiEchelonMat (24.10-1)).

If $$V$$ is a matrix space then B is semi-echelonized if the matrix obtained by replacing each basis vector by the concatenation of its rows is semi-echelonized (see above, cf. SemiEchelonMats (24.10-4)).

gap> V:= GF(2)^2;;
gap> B1:= Basis( V, [ [ 0, 1 ], [ 1, 0 ] ] * Z(2) );;
gap> IsSemiEchelonized( B1 );
true
gap> B2:= Basis( V, [ [ 0, 1 ], [ 1, 1 ] ] * Z(2) );;
gap> IsSemiEchelonized( B2 );
false


##### 61.9-8 SemiEchelonBasis
 ‣ SemiEchelonBasis( V[, vectors] ) ( attribute )
 ‣ SemiEchelonBasisNC( V, vectors ) ( operation )

Let V be a Gaussian row or matrix vector space over the field $$F$$ (see IsGaussianSpace (61.9-3), IsRowSpace (61.9-1), IsMatrixSpace (61.9-2)).

Called with V as the only argument, SemiEchelonBasis returns a basis of V that has the property IsSemiEchelonized (61.9-7).

If additionally a list vectors of vectors in V is given that forms a semi-echelonized basis of V then SemiEchelonBasis returns this basis; if vectors do not form a basis of V then fail is returned.

SemiEchelonBasisNC does the same as the two argument version of SemiEchelonBasis, except that it is not checked whether vectors form a semi-echelonized basis.

gap> V:= GF(2)^2;;
gap> B:= SemiEchelonBasis( V );
SemiEchelonBasis( ( GF(2)^2 ), ... )
gap> Print( BasisVectors( B ), "\n" );
[ [ Z(2)^0, 0*Z(2) ], [ 0*Z(2), Z(2)^0 ] ]
gap> B:= SemiEchelonBasis( V, [ [ 1, 1 ], [ 0, 1 ] ] * Z(2) );
SemiEchelonBasis( ( GF(2)^2 ), <an immutable 2x2 matrix over GF2> )
gap> Print( BasisVectors( B ), "\n" );
[ [ Z(2)^0, Z(2)^0 ], [ 0*Z(2), Z(2)^0 ] ]
gap> Coefficients( B, [ 0, 1 ] * Z(2) );
[ 0*Z(2), Z(2)^0 ]
gap> Coefficients( B, [ 1, 0 ] * Z(2) );
[ Z(2)^0, Z(2)^0 ]
gap> SemiEchelonBasis( V, [ [ 0, 1 ], [ 1, 1 ] ] * Z(2) );
fail


##### 61.9-9 IsCanonicalBasisFullRowModule
 ‣ IsCanonicalBasisFullRowModule( B ) ( property )

IsCanonicalBasisFullRowModule returns true if B is the canonical basis (see IsCanonicalBasis (61.7-1)) of a full row module (see IsFullRowModule (57.3-8)), and false otherwise.

The canonical basis of a Gaussian row space is defined as the unique semi-echelonized (see IsSemiEchelonized (61.9-7)) basis with the additional property that for $$j > i$$ the position of the pivot of row $$j$$ is bigger than the position of the pivot of row $$i$$, and that each pivot column contains exactly one nonzero entry.

##### 61.9-10 IsCanonicalBasisFullMatrixModule
 ‣ IsCanonicalBasisFullMatrixModule( B ) ( property )

IsCanonicalBasisFullMatrixModule returns true if B is the canonical basis (see IsCanonicalBasis (61.7-1)) of a full matrix module (see IsFullMatrixModule (57.3-10)), and false otherwise.

The canonical basis of a Gaussian matrix space is defined as the unique semi-echelonized (see IsSemiEchelonized (61.9-7)) basis for which the list of concatenations of the basis vectors forms the canonical basis of the corresponding Gaussian row space.

##### 61.9-11 NormedRowVectors
 ‣ NormedRowVectors( V ) ( attribute )

For a finite Gaussian row space V (see IsRowSpace (61.9-1), IsGaussianSpace (61.9-3)), NormedRowVectors returns a list of those nonzero vectors in V that have a one in the first nonzero component.

The result list can be used as action domain for the action of a matrix group via OnLines (41.2-12), which yields the natural action on one-dimensional subspaces of V (see also Subspaces (61.4-1)).

gap> vecs:= NormedRowVectors( GF(3)^2 );
[ [ 0*Z(3), Z(3)^0 ], [ Z(3)^0, 0*Z(3) ], [ Z(3)^0, Z(3)^0 ],
[ Z(3)^0, Z(3) ] ]
gap> Action( GL(2,3), vecs, OnLines );
Group([ (3,4), (1,2,4) ])


##### 61.9-12 SiftedVector
 ‣ SiftedVector( B, v ) ( operation )

Let B be a semi-echelonized basis (see IsSemiEchelonized (61.9-7)) of a Gaussian row or matrix space $$V$$ (see IsGaussianSpace (61.9-3)), and v a row vector or matrix, respectively, of the same dimension as the elements in $$V$$. SiftedVector returns the residuum of v with respect to B, which is obtained by successively cleaning the pivot positions in v by subtracting multiples of the basis vectors in B. So the result is the zero vector in $$V$$ if and only if v lies in $$V$$.

B may also be a mutable basis (see 61.8) of a Gaussian row or matrix space.

gap> V:= VectorSpace( Rationals, [ [ 1, 2, 7 ], [ 1/2, 1/3, 5 ] ] );;
gap> B:= Basis( V );;
gap> SiftedVector( B, [ 1, 2, 8 ] );
[ 0, 0, 1 ]


#### 61.10 Vector Space Homomorphisms

Vector space homomorphisms (or linear mappings) are defined in Section 32.11. GAP provides special functions to construct a particular linear mapping from images of given elements in the source, from a matrix of coefficients, or as a natural epimorphism.

$$F$$-linear mappings with same source and same range can be added, so one can form vector spaces of linear mappings.

##### 61.10-1 LeftModuleGeneralMappingByImages
 ‣ LeftModuleGeneralMappingByImages( V, W, gens, imgs ) ( operation )

Let V and W be two left modules over the same left acting domain $$R$$, say, and gens and imgs lists (of the same length) of elements in V and W, respectively. LeftModuleGeneralMappingByImages returns the general mapping with source V and range W that is defined by mapping the elements in gens to the corresponding elements in imgs, and taking the $$R$$-linear closure.

gens need not generate V as a left $$R$$-module, and if the specification does not define a linear mapping then the result will be multi-valued; hence in general it is not a mapping (see IsMapping (32.3-3)).

gap> V:= Rationals^2;;
gap> W:= VectorSpace( Rationals, [ [1,2,3], [1,0,1] ] );;
gap> f:= LeftModuleGeneralMappingByImages( V, W,
>                                [[1,0],[2,0]], [[1,0,1],[1,0,1] ] );
[ [ 1, 0 ], [ 2, 0 ] ] -> [ [ 1, 0, 1 ], [ 1, 0, 1 ] ]
gap> IsMapping( f );
false


##### 61.10-2 LeftModuleHomomorphismByImages
 ‣ LeftModuleHomomorphismByImages( V, W, gens, imgs ) ( function )
 ‣ LeftModuleHomomorphismByImagesNC( V, W, gens, imgs ) ( operation )

Let V and W be two left modules over the same left acting domain $$R$$, say, and gens and imgs lists (of the same length) of elements in V and W, respectively. LeftModuleHomomorphismByImages returns the left $$R$$-module homomorphism with source V and range W that is defined by mapping the elements in gens to the corresponding elements in imgs.

If gens does not generate V or if the homomorphism does not exist (i.e., if mapping the generators describes only a multi-valued mapping) then fail is returned. For creating a possibly multi-valued mapping from V to W that respects addition, multiplication, and scalar multiplication, LeftModuleGeneralMappingByImages (61.10-1) can be used.

LeftModuleHomomorphismByImagesNC does the same as LeftModuleHomomorphismByImages, except that it omits all checks.

gap> V:=Rationals^2;;
gap> W:=VectorSpace( Rationals, [ [ 1, 0, 1 ], [ 1, 2, 3 ] ] );;
gap> f:=LeftModuleHomomorphismByImages( V, W,
> [ [ 1, 0 ], [ 0, 1 ] ], [ [ 1, 0, 1 ], [ 1, 2, 3 ] ] );
[ [ 1, 0 ], [ 0, 1 ] ] -> [ [ 1, 0, 1 ], [ 1, 2, 3 ] ]
gap> Image( f, [1,1] );
[ 2, 2, 4 ]


##### 61.10-3 LeftModuleHomomorphismByMatrix
 ‣ LeftModuleHomomorphismByMatrix( BS, matrix, BR ) ( operation )

Let BS and BR be bases of the left $$R$$-modules $$V$$ and $$W$$, respectively. LeftModuleHomomorphismByMatrix returns the $$R$$-linear mapping from $$V$$ to $$W$$ that is defined by the matrix matrix, as follows. The image of the $$i$$-th basis vector of BS is the linear combination of the basis vectors of BR with coefficients the $$i$$-th row of matrix.

gap> V:= Rationals^2;;
gap> W:= VectorSpace( Rationals, [ [ 1, 0, 1 ], [ 1, 2, 3 ] ] );;
gap> f:= LeftModuleHomomorphismByMatrix( Basis( V ),
> [ [ 1, 2 ], [ 3, 1 ] ], Basis( W ) );
<linear mapping by matrix, ( Rationals^
2 ) -> <vector space over Rationals, with 2 generators>>


##### 61.10-4 NaturalHomomorphismBySubspace
 ‣ NaturalHomomorphismBySubspace( V, W ) ( operation )

For an $$R$$-vector space V and a subspace W of V, NaturalHomomorphismBySubspace returns the $$R$$-linear mapping that is the natural projection of V onto the factor space V / W.

gap> V:= Rationals^3;;
gap> W:= VectorSpace( Rationals, [ [ 1, 1, 1 ] ] );;
gap> f:= NaturalHomomorphismBySubspace( V, W );
<linear mapping by matrix, ( Rationals^3 ) -> ( Rationals^2 )>


##### 61.10-5 Hom
 ‣ Hom( F, V, W ) ( operation )

For a field F and two vector spaces V and W that can be regarded as F-modules (see AsLeftModule (57.1-5)), Hom returns the F-vector space of all F-linear mappings from V to W.

gap> V:= Rationals^2;;
gap> W:= VectorSpace( Rationals, [ [ 1, 0, 1 ], [ 1, 2, 3 ] ] );;
gap> H:= Hom( Rationals, V, W );
Hom( Rationals, ( Rationals^2 ), <vector space over Rationals, with
2 generators> )
gap> Dimension( H );
4


##### 61.10-6 End
 ‣ End( F, V ) ( operation )

For a field F and a vector space V that can be regarded as an F-module (see AsLeftModule (57.1-5)), End returns the F-algebra of all F-linear mappings from V to V.

gap> A:= End( Rationals, Rationals^2 );
End( Rationals, ( Rationals^2 ) )
gap> Dimension( A );
4


##### 61.10-7 IsFullHomModule
 ‣ IsFullHomModule( M ) ( property )

A full hom module is a module of all $$R$$-linear mappings between two left $$R$$-modules. The function Hom (61.10-5) can be used to construct a full hom module.

gap> V:= Rationals^2;;
gap> W:= VectorSpace( Rationals, [ [ 1, 0, 1 ], [ 1, 2, 3 ] ] );;
gap> H:= Hom( Rationals, V, W );;
gap> IsFullHomModule( H );
true


##### 61.10-8 IsPseudoCanonicalBasisFullHomModule
 ‣ IsPseudoCanonicalBasisFullHomModule( B ) ( property )

A basis of a full hom module is called pseudo canonical basis if the matrices of its basis vectors w.r.t. the stored bases of source and range contain exactly one identity entry and otherwise zeros.

Note that this is not a canonical basis (see CanonicalBasis (61.5-3)) because it depends on the stored bases of source and range.

gap> IsPseudoCanonicalBasisFullHomModule( Basis( H ) );
true


##### 61.10-9 IsLinearMappingsModule
 ‣ IsLinearMappingsModule( V ) ( filter )

If an $$F$$-vector space V is in the filter IsLinearMappingsModule then this expresses that V consists of linear mappings, and that V is handled via the mechanism of nice bases (see 61.11), in the following way. Let $$S$$ and $$R$$ be the source and the range, respectively, of each mapping in $$V$$. Then the NiceFreeLeftModuleInfo (61.11-3) value of V is a record with the components basissource (a basis $$B_S$$ of $$S$$) and basisrange (a basis $$B_R$$ of $$R$$), and the NiceVector (61.11-2) value of $$v \in \textit{V}$$ is defined as the matrix of the $$F$$-linear mapping $$v$$ w.r.t. the bases $$B_S$$ and $$B_R$$.

#### 61.11 Vector Spaces Handled By Nice Bases

There are kinds of free $$R$$-modules for which efficient computations are possible because the elements are "nice", for example subspaces of full row modules or of full matrix modules. In other cases, a "nice" canonical basis is known that allows one to do the necessary computations in the corresponding row module, for example algebras given by structure constants.

In many other situations, one knows at least an isomorphism from the given module $$V$$ to a "nicer" free left module $$W$$, in the sense that for each vector in $$V$$, the image in $$W$$ can easily be computed, and analogously for each vector in $$W$$, one can compute the preimage in $$V$$.

This allows one to delegate computations w.r.t. a basis $$B$$, say, of $$V$$ to the corresponding basis $$C$$, say, of $$W$$. We call $$W$$ the nice free left module of $$V$$, and $$C$$ the nice basis of $$B$$. (Note that it may happen that also $$C$$ delegates questions to a "nicer" basis.) The basis $$B$$ indicates the intended behaviour by the filter IsBasisByNiceBasis (61.11-5), and stores $$C$$ as value of the attribute NiceBasis (61.11-4). $$V$$ indicates the intended behaviour by the filter IsHandledByNiceBasis (61.11-6), and stores $$W$$ as value of the attribute NiceFreeLeftModule (61.11-1).

The bijection between $$V$$ and $$W$$ is implemented by the functions NiceVector (61.11-2) and UglyVector (61.11-2); additional data needed to compute images and preimages can be stored as value of NiceFreeLeftModuleInfo (61.11-3).

##### 61.11-1 NiceFreeLeftModule
 ‣ NiceFreeLeftModule( V ) ( attribute )

For a free left module V that is handled via the mechanism of nice bases, this attribute stores the associated free left module to which the tasks are delegated.

##### 61.11-2 NiceVector
 ‣ NiceVector( V, v ) ( operation )
 ‣ UglyVector( V, r ) ( operation )

NiceVector and UglyVector provide the linear bijection between the free left module V and W:= NiceFreeLeftModule( V ).

If v lies in the elements family of the family of V then NiceVector( v ) is either fail or an element in the elements family of the family of W.

If r lies in the elements family of the family of W then UglyVector( r ) is either fail or an element in the elements family of the family of V.

If v lies in V (which usually cannot be checked without using W) then UglyVector( V, NiceVector( V, v ) ) = v. If r lies in W (which usually can be checked) then NiceVector( V, UglyVector( V, r ) ) = r.

(This allows one to implement for example a membership test for V using the membership test in W.)

##### 61.11-3 NiceFreeLeftModuleInfo
 ‣ NiceFreeLeftModuleInfo( V ) ( attribute )

For a free left module V that is handled via the mechanism of nice bases, this operation has to provide the necessary information (if any) for calls of NiceVector (61.11-2) and UglyVector (61.11-2).

##### 61.11-4 NiceBasis
 ‣ NiceBasis( B ) ( attribute )

Let B be a basis of a free left module V that is handled via nice bases. If B has no basis vectors stored at the time of the first call to NiceBasis then NiceBasis( B ) is obtained as Basis( NiceFreeLeftModule( V ) ). If basis vectors are stored then NiceBasis( B ) is the result of the call of Basis with arguments NiceFreeLeftModule( V ) and the NiceVector values of the basis vectors of B.

Note that the result is fail if and only if the "basis vectors" stored in B are in fact not basis vectors.

The attributes GeneratorsOfLeftModule of the underlying left modules of B and the result of NiceBasis correspond via NiceVector (61.11-2) and UglyVector (61.11-2).

##### 61.11-5 IsBasisByNiceBasis
 ‣ IsBasisByNiceBasis( B ) ( category )

This filter indicates that the basis B delegates tasks such as the computation of coefficients (see Coefficients (61.6-3)) to a basis of an isomorphic "nicer" free left module.

##### 61.11-6 IsHandledByNiceBasis
 ‣ IsHandledByNiceBasis( M ) ( category )

For a free left module M in this category, essentially all operations are performed using a "nicer" free left module, which is usually a row module.

#### 61.12 How to Implement New Kinds of Vector Spaces

##### 61.12-1 DeclareHandlingByNiceBasis
 ‣ DeclareHandlingByNiceBasis( name, info ) ( function )
 ‣ InstallHandlingByNiceBasis( name, record ) ( function )

These functions are used to implement a new kind of free left modules that shall be handled via the mechanism of nice bases (see 61.11).

name must be a string, a filter $$f$$ with this name is created, and a logical implication from $$f$$ to IsHandledByNiceBasis (61.11-6) is installed.

record must be a record with the following components.

detect

a function of four arguments $$R$$, $$l$$, $$V$$, and $$z$$, where $$V$$ is a free left module over the ring $$R$$ with generators the list or collection $$l$$, and $$z$$ is either the zero element of $$V$$ or false (then $$l$$ is nonempty); the function returns true if $$V$$ shall lie in the filter $$f$$, and false otherwise; the return value may also be fail, which indicates that $$V$$ is not to be handled via the mechanism of nice bases at all,

NiceFreeLeftModuleInfo

the NiceFreeLeftModuleInfo method for left modules in $$f$$,

NiceVector

the NiceVector method for left modules $$V$$ in $$f$$; called with $$V$$ and a vector $$v \in V$$, this function returns the nice vector $$r$$ associated with $$v$$, and

UglyVector

the UglyVector (61.11-2) method for left modules $$V$$ in $$f$$; called with $$V$$ and a vector $$r$$ in the NiceFreeLeftModule value of $$V$$, this function returns the vector $$v \in V$$ to which $$r$$ is associated.

The idea is that all one has to do for implementing a new kind of free left modules handled by the mechanism of nice bases is to call DeclareHandlingByNiceBasis and InstallHandlingByNiceBasis, which causes the installation of the necessary methods and adds the pair $$[ f,$$record.detect$$]$$ to the global list NiceBasisFiltersInfo. The LeftModuleByGenerators (57.1-10) methods call CheckForHandlingByNiceBasis (61.12-3), which sets the appropriate filter for the desired left module if applicable.

##### 61.12-2 NiceBasisFiltersInfo
 ‣ NiceBasisFiltersInfo ( global variable )

An overview of all kinds of vector spaces that are currently handled by nice bases is given by the global list NiceBasisFiltersInfo. Examples of such vector spaces are vector spaces of field elements (but not the fields themselves) and non-Gaussian row and matrix spaces (see IsGaussianSpace (61.9-3)).

##### 61.12-3 CheckForHandlingByNiceBasis
 ‣ CheckForHandlingByNiceBasis( R, gens, M, zero ) ( function )

Whenever a free left module is constructed for which the filter IsHandledByNiceBasis may be useful, CheckForHandlingByNiceBasis should be called. (This is done in the methods for VectorSpaceByGenerators, AlgebraByGenerators, IdealByGenerators etc. in the GAP library.)

The arguments of this function are the coefficient ring R, the list gens of generators, the constructed module M itself, and the zero element zero of M; if gens is nonempty then the zero value may also be false.

generated by GAPDoc2HTML