% This file was created automatically from vspc.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  vspc.msk                     GAP documentation            Willem de Graaf
%A                                                              Thomas Breuer
%%
%A  @(#)$Id: vspc.msk,v 1.23 2003/07/21 19:49:06 gap Exp $
%%
%Y  (C) 1998 School Math and Comp. Sci., University of St.  Andrews, Scotland
%Y  Copyright (C) 2002 The GAP Group
%%
\Chapter{Vector Spaces}

\>IsLeftVectorSpace( <V> ) C
\>IsVectorSpace( <V> ) C

A *vector space* in {\GAP} is a free left module (see~"IsFreeLeftModule")
over a division ring (see Chapter~"Fields and Division Rings").

Whenever we talk about an $F$-vector space <V> then <V> is an additive
group (see~"IsAdditiveGroup") 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' (see~"LeftActingDomain").

The characteristic (see~"Characteristic") of a vector space is equal to
the characteristic of its left acting domain.

Vector spaces in {\GAP} are always *left* vector spaces,
`IsLeftVectorSpace' and `IsVectorSpace' are synonyms.




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Constructing Vector Spaces}

\>VectorSpace( <F>, <gens>[, <zero>][, "basis"] ) F

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' (see~"Basis") need *not* return the basis formed by
<gens> if the argument `\"basis\"' is given.


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

\>Subspace( <V>, <gens>[, "basis"] ) F
\>SubspaceNC( <V>, <gens>[, "basis"] ) F

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") of
<V> is returned.
The parent (see~"Parents") 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>.


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

\>AsVectorSpace( <F>, <D> ) O

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.


\beginexample
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
\endexample

\>AsSubspace( <V>, <U> ) O

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").
Otherwise `fail' is returned.


\beginexample
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
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Operations and Attributes for Vector Spaces}

\>GeneratorsOfLeftVectorSpace( <V> ) A
\>GeneratorsOfVectorSpace( <V> ) A

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


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

\>TrivialSubspace( <V> ) A

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


\beginexample
gap> V:= GF(3)^3;;
gap> triv:= TrivialSubspace( V );
<vector space over GF(3), with 0 generators>
gap> AsSet( triv );
[ [ 0*Z(3), 0*Z(3), 0*Z(3) ] ]
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Domains of Subspaces of Vector Spaces}

\>Subspaces( <V> ) A
\>Subspaces( <V>, <k> ) O

Let <V> be a finite vector space.  In the first form, `Subspaces' returns
the domain of all subspaces of <V>.
In the second form, <k> must be a nonnegative integer, and `Subspaces'
returns the domain of all <k>-dimensional subspaces of <V>.

Special `Size' and `Iterator' methods are provided for these domains.


\>IsSubspacesVectorSpace( <D> ) C

The domain of all subspaces of a (finite) vector space or of all
subspaces of fixed dimension, as returned by `Subspaces'
(see~"Subspaces") lies in the category `IsSubspacesVectorSpace'.


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

%T The domains of subspaces are useful for example because groups and algebras
%T act on their sets of elements.
%T (show an example)


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{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").
In particular, as each basis is a list (see Chapter~"Lists"),
it has a length (see~"Length"), and the $i$-th vector of $B$ can be
accessed as $B[i]$.
\beginexample
gap> V:= Rationals^3;
( Rationals^3 )
gap> B:= Basis( V );
CanonicalBasis( ( Rationals^3 ) )
gap> Length( B );
3
gap> B[1];
[ 1, 0, 0 ]
\endexample

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~"Basic Operations for Lists"),
the *basic operations for bases* are `BasisVectors' (see~"BasisVectors"),
`Coefficients' (see~"Coefficients"),
`LinearCombination' (see~"LinearCombination"),
and `UnderlyingLeftModule' (see~"UnderlyingLeftModule").
These and other operations for arbitrary bases are described
in~"Operations for Vector Space Bases".

For special kinds of bases, further operations are defined
(see~"Operations for Special Kinds of Bases").

{\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").

*Bases handled by nice bases* delegate the work to bases
of isomorphic left modules over the same left acting domain
(see~"Vector Spaces Handled By Nice Bases").

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~"Row and Matrix Spaces"),
`Basis( <V> )' is a semi-echelonized basis (see~"IsSemiEchelonized")
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~"Vector Spaces Handled By Nice Bases".
Examples are non-Gaussian row and matrix spaces, and subspaces of finite
fields and abelian number fields that are themselves not fields.



\>IsBasis( <obj> ) C

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").
Bases are constructed by `Basis' (see~"Basis").
Each basis is an immutable list,
the $i$-th entry being the $i$-th basis vector.

(See~"Mutable Bases" for mutable bases.)


\beginexample
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
\endexample

\>Basis( <V> ) A
\>Basis( <V>, <vectors> ) O
\>BasisNC( <V>, <vectors> ) O

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 `Basis' for two arguments,
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'.


\beginexample
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
\endexample

%T show the use of the ``no check'' version

\>CanonicalBasis( <V> ) A

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") 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~"Row and Matrix Spaces").

If one designs a new kind of vector spaces
(see~"How to Implement New Kinds of Vector Spaces") and defines a
canonical basis for these spaces then the `CanonicalBasis' method
one installs (see~"prg:InstallMethod" in ``Programming in {\GAP}'')
must *not* call `Basis'.  On the other hand, one probably should install
a `Basis' method that simply calls `CanonicalBasis', the value of the
method (see~"prg:Method Installation"
and~"prg:Applicable Methods and Method Selection" in ``Programming in
{\GAP}'') being `CANONICAL_BASIS_FLAGS'.


\beginexample
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 ] ]
\endexample

\>RelativeBasis( <B>, <vectors> ) O
\>RelativeBasisNC( <B>, <vectors> ) O

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.




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Operations for Vector Space Bases}

\>BasisVectors( <B> ) A

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.


\beginexample
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 ] ]
\endexample

\>UnderlyingLeftModule( <B> ) A

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");
furthermore, in some cases it is convenient to test membership of a
vector in the module before computing coefficients w.r.t.~a basis.


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

\>Coefficients( <B>, <v> ) O

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.


\beginexample
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
\endexample

\>LinearCombination( <B>, <coeff> ) O
\>LinearCombination( <vectors>, <coeff> ) O

If <B> is a basis of length $n$, say, and <coeff> is a row vector of the
same length as <B>, `LinearCombination' returns the vector
$\sum_{i=1}^n <coeff>[i] \* <B>[i]$.

If <vectors> and <coeff> are homogeneous lists of the same length <n>,
say, `LinearCombination' returns the vector
$\sum_{i=1}^n <coeff>[i]\*<vectors>[i]$.
Perhaps the most important usage is the case where <vectors> forms a 
basis.


\beginexample
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 ]
\endexample

\>EnumeratorByBasis( <B> ) A

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") of dimension $n$
over $F$, in the succession given by the default enumerator of this row
space.


\beginexample
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) ] ]
\endexample

\>IteratorByBasis( <B> ) O

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") of dimension $n$ over
$F$, in the succession given by the default enumerator of this row space.


\beginexample
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) ]
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Operations for Special Kinds of Bases}

\>IsCanonicalBasis( <B> ) P

If the underlying free left module $V$ of the basis <B> supports a
canonical basis (see~"CanonicalBasis") then `IsCanonicalBasis' returns
`true' if <B> is equal to the canonical basis of $V$,
and `false' otherwise.



\>IsIntegralBasis( <B> ) P

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.


\>IsNormalBasis( <B> ) P

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!of field") of the field extension $F / S$,
and `false' otherwise.


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

% add an example of a non-integral basis;
% for that, add a method that takes an integral basis,
% and inspects the basechange matrix

\>StructureConstantsTable( <B> ) A

Let <B> be a basis of a free left module $R$, say, that is also a ring.
In this case `StructureConstantsTable' returns a structure constants
table $T$ in sparse representation, as used for structure constants
algebras (see Section~"tut:Algebras" of the {\GAP} User's Tutorial).

If <B> has length $n$ then $T$ is a list of length $n+2$.
The first $n$ entries of $T$ are lists of length $n$.
$T[ n+1 ]$ is one of $1$, $-1$, or $0$;
in the case of $1$ the table is known to be symmetric,
in the case of $-1$ it is known to be antisymmetric,
and $0$ occurs in all other cases.
$T[ n+2 ]$ is the zero element of the coefficient domain.

The coefficients w.r.t.~<B> of the product of the $i$-th and $j$-th basis
vector of <B> are stored in $T[i][j]$ as a list of length $2$;
its first entry is the list of positions of nonzero coefficients,
the second entry is the list of these coefficients themselves.

The multiplication in an algebra $A$ with vector space basis <B>
with basis vectors $[ v_1, \ldots, v_n ]$ is determined by the so-called
structure matrices $M_k = [ m_{ijk} ]_{ij}, 1 \leq k \leq n$.
The $M_k$ are defined by $v_i v_j = \sum_k m_{i,j,k} v_k$.
Let $a = [ a_1, \ldots, a_n ]$ and $b = [ b_1, \ldots, b_n ]$.
Then
$$
( \sum_i a_i v_i ) ( \sum_j b_j v_j )
   = \sum_{i,j} a_i b_j ( v_i v_j )
   = \sum_k ( \sum_j ( \sum_i a_i m_{i,j,k} ) b_j ) v_k
   = \sum_k ( a M_k b^{tr} ) v_k\.
$$



In the following example we temporarily increase the line length limit from
its default value 80 to 83 in order to get a nicer output format.

\beginexample
gap> A:= QuaternionAlgebra( Rationals );;
gap> SizeScreen([ 83, ]);;
gap> StructureConstantsTable( Basis( A ) );
[ [ [ [ 1 ], [ 1 ] ], [ [ 2 ], [ 1 ] ], [ [ 3 ], [ 1 ] ], [ [ 4 ], [ 1 ] ] ], 
  [ [ [ 2 ], [ 1 ] ], [ [ 1 ], [ -1 ] ], [ [ 4 ], [ 1 ] ], [ [ 3 ], [ -1 ] ] ], 
  [ [ [ 3 ], [ 1 ] ], [ [ 4 ], [ -1 ] ], [ [ 1 ], [ -1 ] ], [ [ 2 ], [ 1 ] ] ], 
  [ [ [ 4 ], [ 1 ] ], [ [ 3 ], [ 1 ] ], [ [ 2 ], [ -1 ] ], [ [ 1 ], [ -1 ] ] ], 
  0, 0 ]
gap> SizeScreen([ 80, ]);;
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{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").

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'
(see~"NrBasisVectors"), `IsContainedInSpan' (see~"IsContainedInSpan"),
`CloseMutableBasis' (see~"CloseMutableBasis"),
`ImmutableBasis' (see~"ImmutableBasis"), `Coefficients'
(see~"Coefficients"), and `BasisVectors' (see~"BasisVectors").
`ShallowCopy' (see~"ShallowCopy") 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~"Families")
equals the family of its collection of basis vectors.

Mutable bases can be constructed with `MutableBasis'.

Similar to the situation with bases (cf.~"Bases of Vector Spaces"),
{\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~"Vector Spaces Handled By Nice Bases") 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.



\>IsMutableBasis( <MB> ) C

Every mutable basis lies in the category `IsMutableBasis'.



\>MutableBasis( <R>, <vectors>[, <zero>] ) O

`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!


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

\>NrBasisVectors( <MB> ) O

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.


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

\>ImmutableBasis( <MB>[, <V>] ) O

`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' (see~"UnderlyingLeftModule") 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.


\beginexample
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>
\endexample

\>IsContainedInSpan( <MB>, <v> ) O

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.


\>CloseMutableBasis( <MB>, <v> ) O

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").


\beginexample
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 ] );
gap> MB;
<mutable basis over Rationals, 3 vectors>
gap> IsContainedInSpan( MB, [ 1, 0, 0 ] );
true
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Row and Matrix Spaces}

\index{row spaces}
\index{matrix spaces}

\>IsRowSpace( <V> ) F

A *row space* in {\GAP} is a vector space that consists of row vectors
(see Chapter~"Row Vectors").


\>IsMatrixSpace( <V> ) F

A *matrix space* in {\GAP} is a vector space that consists of matrices
(see Chapter~"Matrices").



\>IsGaussianSpace( <V> ) F

The filter `IsGaussianSpace' (see~"Filters") for the row space
(see~"IsRowSpace") or matrix space (see~"IsMatrixSpace") <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.


\beginexample
gap> mats:= [ [[1,1],[2,2]], [[3,4],[0,1]] ];;
gap> V:= VectorSpace( Rationals, mats );;
gap> IsGaussianSpace( V );
true
gap> mats[1][1][1]:= 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
\endexample

\>FullRowSpace( <F>, <n> ) F

For a field <F> and a nonnegative integer <n>, `FullRowSpace' returns the
<F>-vector space that consists of all row vectors (see~"IsRowVector") of
length <n> with entries in <F>.

An alternative to construct this vector space is via `<F>^<n>'.


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

\>FullMatrixSpace( <F>, <m>, <n> ) F

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") with entries in <F>.

If `<m> = <n>' then the result is in fact an algebra
(see~"FullMatrixAlgebra").

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


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

\>DimensionOfVectors( <M> ) A

For a left module <M> that consists of row vectors (see~"IsRowModule"),
`DimensionOfVectors' returns the common length of all row vectors in <M>.
For a left module <M> that consists of matrices (see~"IsMatrixModule"),
`DimensionOfVectors' returns the common matrix dimensions
(see~"DimensionsMat") of all matrices in <M>.


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

\>IsSemiEchelonized( <B> ) P

Let <B> be a basis of a Gaussian row or matrix space $V$, say
(see~"IsGaussianSpace") 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").

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").


\beginexample
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
\endexample

\>SemiEchelonBasis( <V> ) A
\>SemiEchelonBasis( <V>, <vectors> ) O
\>SemiEchelonBasisNC( <V>, <vectors> ) O

Let <V> be a Gaussian row or matrix vector space over the field $F$
(see~"IsGaussianSpace", "IsRowSpace", "IsMatrixSpace").

Called with <V> as the only argument,
`SemiEchelonBasis' returns a basis of <V> that has the property
`IsSemiEchelonized' (see~"IsSemiEchelonized").

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 `SemiEchelonBasis' for two
arguments,
except that it is not checked whether <vectors> form
a semi-echelonized basis.


\beginexample
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
\endexample

\index{canonical basis!for row spaces}

\>IsCanonicalBasisFullRowModule( <B> ) P

`IsCanonicalBasisFullRowModule' returns `true' if <B> is the canonical
basis (see~"IsCanonicalBasis") of a full row module
(see~"IsFullRowModule"), and `false' otherwise.



The *canonical basis* of a Gaussian row space is defined as the unique
semi-echelonized (see~"IsSemiEchelonized") 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.

\index{canonical basis!for matrix spaces}

\>IsCanonicalBasisFullMatrixModule( <B> ) P

`IsCanonicalBasisFullMatrixModule' returns `true' if <B> is the canonical
basis (see~"IsCanonicalBasis") of a full matrix module
(see~"IsFullMatrixModule"), and `false' otherwise.



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

\>NormedRowVectors( <V> ) A

For a finite Gaussian row space <V> (see~"IsRowSpace",
"IsGaussianSpace"), `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' (see~"OnLines"), which yields the natural action on
one-dimensional subspaces of <V> (see also~"Subspaces").


\beginexample
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) ])
\endexample

\>SiftedVector( <B>, <v> ) O

Let <B> be a semi-echelonized basis (see~"IsSemiEchelonized") of a
Gaussian row or matrix space $V$ (see~"IsGaussianSpace"),
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~"Mutable Bases") of a Gaussian row
or matrix space.


\beginexample
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 ]
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Vector Space Homomorphisms}

*Vector space homomorphisms* (or *linear mappings*) are defined in
Section~"Linear Mappings".
{\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.



\>LeftModuleGeneralMappingByImages( <V>, <W>, <gens>, <imgs> ) O

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").


\beginexample
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
\endexample

\>LeftModuleHomomorphismByImages( <V>, <W>, <gens>, <imgs> ) F
\>LeftModuleHomomorphismByImagesNC( <V>, <W>, <gens>, <imgs> ) O

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' can be used.

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


\beginexample
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 ]
\endexample

% add an example for fin. fields!

\>LeftModuleHomomorphismByMatrix( <BS>, <matrix>, <BR> ) O

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>.


\beginexample
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>>
\endexample

% show images!

\>NaturalHomomorphismBySubspace( <V>, <W> ) O

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>'.


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

% show the computation of images etc.!

\>Hom( <F>, <V>, <W> ) O

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


\beginexample
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
\endexample

\>End( <F>, <V> ) O

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


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

\>IsFullHomModule( <M> ) P

A *full hom module* is a module of all $R$-linear mappings between two
left $R$-modules.  The function `Hom' (see~"Hom") can be used to
construct a full hom module.


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

\>IsPseudoCanonicalBasisFullHomModule( <B> ) P

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")
because it depends on the stored bases of source and range.


\beginexample
gap> IsPseudoCanonicalBasisFullHomModule( Basis( H ) );
true
\endexample

\>IsLinearMappingsModule( <V> ) F

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~"Vector Spaces Handled By Nice Bases") in the following way.
Let $S$ and $R$ be the source and the range, respectively, of each
mapping in $V$.
Then the `NiceFreeLeftModuleInfo' 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' value of $v \in <V>$ is defined as the
matrix of the $F$-linear mapping $v$ w.r.t.~the bases $B_S$ and $B_R$.



% example: Create a space, show some computations!


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{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' (see~"IsBasisByNiceBasis"),
and stores $C$ as value of the attribute `NiceBasis' (see~"NiceBasis").
$V$ indicates the intended behaviour by the filter `IsHandledByNiceBasis'
(see~"IsHandledByNiceBasis!for vector spaces"), and stores $W$  as  value
of the attribute `NiceFreeLeftModule' (see~"NiceFreeLeftModule").

The bijection between $V$ and $W$ is implemented by the functions
`NiceVector' (see~"NiceVector") and `UglyVector' (see~"UglyVector");
additional data needed to compute images and preimages can be stored
as value of `NiceFreeLeftModuleInfo' (see~"NiceFreeLeftModuleInfo").



\>NiceFreeLeftModule( <V> ) A

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.


\>NiceVector( <V>, <v> ) O
\>UglyVector( <V>, <r> ) O

`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>.)


\>NiceFreeLeftModuleInfo( <V> ) A

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' and `UglyVector' (see~"NiceVector").


\>NiceBasis( <B> ) A

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' and
`UglyVector'.


\>IsBasisByNiceBasis( <B> ) C

This filter indicates that the basis <B> delegates tasks such as the
computation of coefficients (see~"Coefficients") to a basis of an
isomorphisc ``nicer'' free left module.



\>IsHandledByNiceBasis( <M> )!{for vector spaces} C

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.




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{How to Implement New Kinds of Vector Spaces}

% put this into the `prg' or `ext' manual?

\>DeclareHandlingByNiceBasis( <name>, <info> ) F
\>InstallHandlingByNiceBasis( <name>, <record> ) F

These functions are used to implement a new kind of free left modules
that shall be handled via the mechanism of nice bases
(see~"Vector Spaces Handled By Nice Bases").

<name> must be a string, a filter $f$ with this name is created, and
a logical implication from $f$ to `IsHandledByNiceBasis'
(see~"IsHandledByNiceBasis!for vector spaces") is installed.

<record> must be a record with the following components.
\beginitems
`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' 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.
\enditems

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' methods call `CheckForHandlingByNiceBasis'
(see~"CheckForHandlingByNiceBasis"), which sets the appropriate filter
for the desired left module if applicable.


\>`NiceBasisFiltersInfo' V

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").


\>CheckForHandlingByNiceBasis( <R>, <gens>, <M>, <zero> ) F

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'.




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E