% This file was created automatically from module.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  module.msk                   GAP documentation              Thomas Breuer
%%
%A  @(#)$Id: module.msk,v 1.12 2002/04/15 10:02:30 sal Exp $
%%
%Y  (C) 1998 School Math and Comp. Sci., University of St.  Andrews, Scotland
%Y  Copyright (C) 2002 The GAP Group
%%
\PreliminaryChapter{Modules}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Generating modules}

\>IsLeftOperatorAdditiveGroup( <D> ) C

A domain <D> lies in `IsLeftOperatorAdditiveGroup' if it is an additive
group that is closed under scalar multplication from the
left, and such that $\lambda*(x+y)=\lambda*x+\lambda*y$ for all
scalars $\lambda$ and elements $x,y\in D$.


\>IsLeftModule( <M> ) C

A domain <M> lies in `IsLeftModule' if it lies in
`IsLeftOperatorAdditiveGroup', {\it and} the set of scalars forms a ring,
{\it and} $(\lambda+\mu)*x=\lambda*x+\mu*x$ for scalars $\lambda,\mu$
and $x\in M$, {\it and} scalar multiplication satisfies $\lambda*(\mu*x)=
(\lambda*\mu)*x$ for scalars $\lambda,\mu$ and $x\in M$.



\beginexample
gap> V:= FullRowSpace( Rationals, 3 );
( Rationals^3 )
gap> IsLeftModule( V );
true
\endexample

\>GeneratorsOfLeftOperatorAdditiveGroup( <D> ) A

returns a list of elements of <D> that generates <D> as a left operator
additive group.


\>GeneratorsOfLeftModule( <M> ) A

returns a list of elements of <M> that generate <M> as a left module.



\beginexample
gap> V:= FullRowSpace( Rationals, 3 );;
gap> GeneratorsOfLeftModule( V );
[ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ]
\endexample

\>AsLeftModule( <R>, <D> ) O

if the domain <D> forms an additive group and is closed under left
multiplication by the elements of <R>, then `AsLeftModule( <R>, <D> )'
returns the domain <D> viewed as a left module.



\beginexample
gap> coll:= [ [0*Z(2),0*Z(2)], [Z(2),0*Z(2)], [0*Z(2),Z(2)], [Z(2),Z(2)] ];
[ [ 0*Z(2), 0*Z(2) ], [ Z(2)^0, 0*Z(2) ], [ 0*Z(2), Z(2)^0 ], 
  [ Z(2)^0, Z(2)^0 ] ]
gap> AsLeftModule( GF(2), coll );
<vector space of dimension 2 over GF(2)>
\endexample

\>IsRightOperatorAdditiveGroup( <D> ) C

A domain <D> lies in `IsRightOperatorAdditiveGroup' if it is an additive
group that is closed under scalar multplication from the
right, and such that $(x+y)*\lambda=x*\lambda+y*\lambda$ for all
scalars $\lambda$ and elements $x,y\in D$.


\>IsRightModule( <M> ) C

A domain <M> lies in `IsRightModule' if it lies in
`IsRightOperatorAdditiveGroup', {\it and} the set of scalars forms a ring,
{\it and} $x*(\lambda+\mu) = x*\lambda+x*\mu$ for scalars $\lambda,\mu$
and $x\in M$, {\it and} scalar multiplication satisfies $(x*\mu)*\lambda=
x*(\mu*\lambda)$ for scalars $\lambda,\mu$ and $x\in M$.


\>GeneratorsOfRightOperatorAdditiveGroup( <D> ) A

returns a list of elements of <D> that generates <D> as a right operator
additive group.


\>GeneratorsOfRightModule( <M> ) A

returns a list of elements of <M> that generate <M> as a left module.



\>LeftModuleByGenerators( <R>, <gens> ) O
\>LeftModuleByGenerators( <R>, <gens>, <zero> ) O

returns the left module over <R> generated by <gens>.



\beginexample
gap> coll:= [ [Z(2),0*Z(2)], [0*Z(2),Z(2)], [Z(2),Z(2)] ];;
gap> V:= LeftModuleByGenerators( GF(16), coll );
<vector space over GF(2^4), with 3 generators>
\endexample

\>LeftActingDomain( <D> ) A

Let <D> be an external left set, that is, <D> is closed under the action
of a domain $L$ by multiplication from the left.
Then $L$ can be accessed as value of `LeftActingDomain' for <D>.




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Submodules}

\>Submodule( <M>, <gens> ) F
\>Submodule( <M>, <gens>, "basis" ) F

is the left module generated by the collection <gens>,
with parent module <M>.
The second form generates the submodule of <M> for that the list <gens>
is known to be a list of basis vectors;
in this case, it is *not* checked whether <gens> really are linearly
independent and whether all in <gens> lie in <M>.



\beginexample
gap> coll:= [ [Z(2),0*Z(2)], [0*Z(2),Z(2)], [Z(2),Z(2)] ];;
gap> V:= LeftModuleByGenerators( GF(16), coll );;
gap> W:= Submodule( V, [ coll[1], coll[2] ] );
<vector space over GF(2^4), with 2 generators>
gap> Parent( W ) = V;
true
\endexample

\>SubmoduleNC( <M>, <gens> ) F
\>SubmoduleNC( <M>, <gens>, "basis" ) F

`SubmoduleNC' does the same as `Submodule', except that it does not check
whether all in <gens> lie in <M>.


\>ClosureLeftModule( <M>, <m> ) O

is the left module generated by the left module generators of <M> and the
element <m>.



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

\>TrivialSubmodule( <M> ) A

returns the zero submodule of <M>.



\beginexample
gap> V:= LeftModuleByGenerators( Rationals, [ [ 1, 0, 0 ], [ 0, 1, 0 ] ] );;
gap> TrivialSubmodule( V );
<vector space over Rationals, with 0 generators>
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Free Modules}

\>IsFreeLeftModule( <M> ) C

A left module is free as module if it is isomorphic to a direct sum of
copies of its left acting domain.

Free left modules can have bases.

The characteristic (see~"Characteristic") of a free left module
is defined as the characteristic of its left acting domain
(see~"LeftActingDomain").


\>FreeLeftModule( <R>, <gens> ) F
\>FreeLeftModule( <R>, <gens>, <zero> ) F
\>FreeLeftModule( <R>, <gens>, "basis" ) F
\>FreeLeftModule( <R>, <gens>, <zero>, "basis" ) F

`FreeLeftModule( <R>, <gens> )' is the free left module over the ring
<R>, generated by the vectors in the collection <gens>.

If there are three arguments, a ring <R> and a collection <gens>
and an element <zero>,
then `FreeLeftModule( <R>, <gens>, <zero> )' is the <R>-free left module
generated by <gens>, with zero element <zero>.

If the last argument is the string `"basis"' then the vectors in
<gens> are known to form a basis of the free module.

It should be noted that the generators <gens> must be vectors,
that is, they must support an addition and a scalar action of <R>
via left multiplication.
(See also Section~"Constructing Domains" for the general meaning of
``generators'' in {\GAP}.)
In particular, `FreeLeftModule' is *not* an equivalent of commands
such as `FreeGroup' (see~"FreeGroup") in the sense of a constructor of
a free group on abstract generators;
Such a construction seems to be unnecessary for vector spaces,
for that one can use for example row spaces (see~"FullRowSpace")
in the finite dimensional case
and polynomial rings (see~"PolynomialRing") in the infinite dimensional
case.
Moreover, the definition of a ``natural'' addition for elements of a
given magma (for example a permutation group) is possible via the
construction of magma rings (see Chapter "ref:Magma Rings").



\beginexample
gap> V:= FreeLeftModule( Rationals, [ [ 1, 0, 0 ], [ 0, 1, 0 ] ], "basis" );
<vector space of dimension 2 over Rationals>
\endexample

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

if the domain <D> is a free left module over <F>, then
`AsFreeLeftModule( <F>, <D> )' returns the domain <D> viewed as free
 left module over <F>.



\>Dimension( <M> ) A

A free left module has dimension $n$ if it is isomorphic to a direct sum
of $n$ copies of its left acting domain.

(We do *not* mark `Dimension' as invariant under isomorphisms
since we want to call `UseIsomorphismRelation' also for free left modules
over different left acting domains.)



\beginexample
gap> V:= FreeLeftModule( Rationals, [ [ 1, 0 ], [ 0, 1 ], [ 1, 1 ] ] );;
gap> Dimension( V );
2
\endexample

\>IsFiniteDimensional( <M> ) P

is `true' if <M> is a free left module that is finite dimensional
over its left acting domain, and `false' otherwise.



\beginexample
gap> V:= FreeLeftModule( Rationals, [ [ 1, 0 ], [ 0, 1 ], [ 1, 1 ] ] );;
gap> IsFiniteDimensional( V );
true
\endexample

\>UseBasis( <V>, <gens> ) O

The vectors in the list <gens> are known to form a basis of the
free left module <V>.
`UseBasis' stores information in <V> that can be derived form this fact,
namely
\beginlist%unordered
\item{--}
  <gens> are stored as left module generators if no such generators were
  bound (this is useful especially if <V> is an algebra),
\item{--}
  the dimension of <V> is stored.
\endlist



\beginexample
gap> V:= FreeLeftModule( Rationals, [ [ 1, 0 ], [ 0, 1 ], [ 1, 1 ] ] );;
gap> UseBasis( V, [ [ 1, 0 ], [ 1, 1 ] ] );
gap> V;  # now V knows its dimension
<vector space of dimension 2 over Rationals>
\endexample


\>IsRowModule( <V> ) P

A *row module* is a free left module whose elements are row vectors.


\>IsMatrixModule( <V> ) P

A *matrix module* is a free left module whose elements are matrices.


\>IsFullRowModule( <M> ) P

A *full row module* is a module $R^n$,
for a ring $R$ and a nonnegative integer $n$.

More precisely, a full row module is a free left module over a ring $R$
such that the elements are row vectors with entries in $R$ and such that
the dimension is equal to the length of the row vectors.

Several functions delegate their tasks to full row modules,
for example `Iterator' and `Enumerator'.


\>FullRowModule( <R>, <n> ) F

is the row module `<R>^<n>',
for a ring <R> and a nonnegative integer <n>.



\beginexample
gap> V:= FullRowModule( Integers, 5 );
( Integers^5 )
\endexample

\>IsFullMatrixModule( <M> ) P

A *full matrix module* is a module $R^{[m,n]}$,
for a ring $R$ and two nonnegative integers $m$, $n$.

More precisely, a full matrix module is a free left module over a ring
$R$ such that the elements are matrices with entries in $R$
and such that the dimension is equal to the number of entries in each
matrix.


\>FullMatrixModule( <R>, <m>, <n> ) F

is the row module `<R>^[<m>,<n>]',
for a ring <R> and nonnegative integers <m> and <n>.



\beginexample
gap> FullMatrixModule( GaussianIntegers, 3, 6 );
( GaussianIntegers^[ 3, 6 ] )
\endexample


\>IsHandledByNiceBasis( <M> ) 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.