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