### 57 Modules

#### 57.1 Generating modules

 ‣ IsLeftOperatorAdditiveGroup( D ) ( category )

A domain D lies in IsLeftOperatorAdditiveGroup if it is an additive group that is closed under scalar multiplication from the left, and such that $$\lambda * ( x + y ) = \lambda * x + \lambda * y$$ for all scalars $$\lambda$$ and elements $$x, y \in D$$ (here and below by scalars we mean elements of a domain acting on D from left or right as appropriate).

##### 57.1-2 IsLeftModule
 ‣ IsLeftModule( M ) ( category )

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

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


 ‣ GeneratorsOfLeftOperatorAdditiveGroup( D ) ( attribute )

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

##### 57.1-4 GeneratorsOfLeftModule
 ‣ GeneratorsOfLeftModule( M ) ( attribute )

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

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


##### 57.1-5 AsLeftModule
 ‣ AsLeftModule( R, D ) ( operation )

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.

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


 ‣ IsRightOperatorAdditiveGroup( D ) ( category )

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

##### 57.1-7 IsRightModule
 ‣ IsRightModule( M ) ( category )

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

 ‣ GeneratorsOfRightOperatorAdditiveGroup( D ) ( attribute )

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

##### 57.1-9 GeneratorsOfRightModule
 ‣ GeneratorsOfRightModule( M ) ( attribute )

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

##### 57.1-10 LeftModuleByGenerators
 ‣ LeftModuleByGenerators( R, gens[, zero] ) ( operation )

returns the left module over R generated by gens.

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>


##### 57.1-11 LeftActingDomain
 ‣ LeftActingDomain( D ) ( attribute )

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.

#### 57.2 Submodules

##### 57.2-1 Submodule
 ‣ Submodule( M, gens[, "basis"] ) ( function )

is the left module generated by the collection gens, with parent module M. If the string "basis" is entered as the third argument then the submodule of M is created for which the list gens is known to be a list of basis vectors; in this case, it is not checked whether gens really is linearly independent and whether all in gens lie in M.

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


##### 57.2-2 SubmoduleNC
 ‣ SubmoduleNC( M, gens[, "basis"] ) ( function )

SubmoduleNC does the same as Submodule (57.2-1), except that it does not check whether all in gens lie in M.

##### 57.2-3 ClosureLeftModule
 ‣ ClosureLeftModule( M, m ) ( operation )

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

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>


##### 57.2-4 TrivialSubmodule
 ‣ TrivialSubmodule( M ) ( attribute )

returns the zero submodule of M.

gap> V:= LeftModuleByGenerators(Rationals, [[ 1, 0, 0 ], [ 0, 1, 0 ]]);;
gap> TrivialSubmodule( V );
<vector space of dimension 0 over Rationals>


#### 57.3 Free Modules

##### 57.3-1 IsFreeLeftModule
 ‣ IsFreeLeftModule( M ) ( category )

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 (31.10-1)) of a free left module is defined as the characteristic of its left acting domain (see LeftActingDomain (57.1-11)).

##### 57.3-2 FreeLeftModule
 ‣ FreeLeftModule( R, gens[, zero][, "basis"] ) ( function )

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 31.3 for the general meaning of "generators" in GAP.) In particular, FreeLeftModule is not an equivalent of commands such as FreeGroup (37.2-1) 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 (61.9-4)) in the finite dimensional case and polynomial rings (see PolynomialRing (66.15-1)) 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 65).

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


##### 57.3-3 Dimension
 ‣ Dimension( M ) ( attribute )

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 (31.13-3) also for free left modules over different left acting domains.)

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


##### 57.3-4 IsFiniteDimensional
 ‣ IsFiniteDimensional( M ) ( property )

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

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


##### 57.3-5 UseBasis
 ‣ UseBasis( V, gens ) ( operation )

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

• gens are stored as left module generators if no such generators were bound (this is useful especially if V is an algebra),

• the dimension of V is stored.

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>


##### 57.3-6 IsRowModule
 ‣ IsRowModule( V ) ( property )

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

##### 57.3-7 IsMatrixModule
 ‣ IsMatrixModule( V ) ( property )

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

##### 57.3-8 IsFullRowModule
 ‣ IsFullRowModule( M ) ( property )

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 of the same length $$n$$ and with entries in $$R$$ and such that the dimension is equal to $$n$$.

Several functions delegate their tasks to full row modules, for example Iterator (30.8-1) and Enumerator (30.3-2).

##### 57.3-9 FullRowModule
 ‣ FullRowModule( R, n ) ( function )

is the row module R^n, for a ring R and a nonnegative integer n.

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


##### 57.3-10 IsFullMatrixModule
 ‣ IsFullMatrixModule( M ) ( property )

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 $$m$$ by $$n$$ matrices with entries in $$R$$ and such that the dimension is equal to $$m n$$.

##### 57.3-11 FullMatrixModule
 ‣ FullMatrixModule( R, m, n ) ( function )

is the matrix module R^[m,n], for a ring R and nonnegative integers m and n.

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


generated by GAPDoc2HTML