7 Modules
  
  A  homalg  module  is  a  data  structure for a finitely presented module. A
  presentation  is  given  by a set of generators and a set of relations among
  these  generators.  The  data  structure for modules in homalg has two novel
  features:
  
      The  data structure allows several presentations linked with so-called
        transition matrices. One of the presentations is marked as the default
        presentation,  which is usually the last added one. A new presentation
        can  always be added provided it is linked to the default presentation
        by  a  transition  matrix.  If  needed, the user can reset the default
        presentation  by  choosing one of the other presentations saved in the
        data  structure  of  the  homalg module. Effectively, a module is then
        given   by  all  its  presentations  (as  coordinates)  together  with
        isomorphisms  between  them  (as  coordinate  changes).  Being able to
        change  coordinates  makes  the  realization  of  a  module  in homalg
        intrinsic (or coordinate free).
  
      To  present  a  left/right  module  it suffices to take a matrix M and
        interpret  its  rows/columns as relations among n abstract generators,
        where  n  is the number of columns/rows of M. Only that these abstract
        generators  are useless when it comes to specific modules like modules
        of  homomorphisms, where one expects the generators to be maps between
        modules.  For  this reason a presentation of a module in homalg is not
        merely a matrix of relations, but together with a set of generators.
  
  
  7.1 Modules: Category and Representations
  
  7.1-1 IsHomalgModule
  
  IsHomalgModule( M )  Category
  Returns:  true or false
  
  The GAP category of homalg modules.
  
  (It  is  a  subcategory  of  the  GAP  categories  IsHomalgRingOrModule  and
  IsHomalgStaticObject.)
  
    Code  
    DeclareCategory( "IsHomalgModule",
            IsHomalgRingOrModule and
            IsHomalgModuleOrMap and
            IsHomalgStaticObject );
  
  
  7.1-2 IsFinitelyPresentedModuleOrSubmoduleRep
  
  IsFinitelyPresentedModuleOrSubmoduleRep( M )  Representation
  Returns:  true or false
  
  The GAP representation of finitley presented homalg modules or submodules.
  
  (It is a representation of the GAP category IsHomalgModule (7.1-1), which is
  a       subrepresentation       of       the       GAP       representations
  IsStaticFinitelyPresentedObjectOrSubobjectRep.)
  
    Code  
    DeclareRepresentation( "IsFinitelyPresentedModuleOrSubmoduleRep",
            IsHomalgModule and
            IsStaticFinitelyPresentedObjectOrSubobjectRep,
            [ ] );
  
  
  7.1-3 IsFinitelyPresentedModuleRep
  
  IsFinitelyPresentedModuleRep( M )  Representation
  Returns:  true or false
  
  The GAP representation of finitley presented homalg modules.
  
  (It is a representation of the GAP category IsHomalgModule (7.1-1), which is
  a       subrepresentation       of       the       GAP       representations
  IsFinitelyPresentedModuleOrSubmoduleRep, IsStaticFinitelyPresentedObjectRep,
  and IsHomalgRingOrFinitelyPresentedModuleRep.)
  
    Code  
    DeclareRepresentation( "IsFinitelyPresentedModuleRep",
            IsFinitelyPresentedModuleOrSubmoduleRep and
            IsStaticFinitelyPresentedObjectRep and
            IsHomalgRingOrFinitelyPresentedModuleRep,
            [ "SetsOfGenerators", "SetsOfRelations",
              "PresentationMorphisms",
              "Resolutions",
              "TransitionMatrices",
              "PositionOfTheDefaultPresentation" ] );
  
  
  7.1-4 IsFinitelyPresentedSubmoduleRep
  
  IsFinitelyPresentedSubmoduleRep( M )  Representation
  Returns:  true or false
  
  The GAP representation of finitley generated homalg submodules.
  
  (It is a representation of the GAP category IsHomalgModule (7.1-1), which is
  a       subrepresentation       of       the       GAP       representations
  IsFinitelyPresentedModuleOrSubmoduleRep,
  IsStaticFinitelyPresentedSubobjectRep,                                   and
  IsHomalgRingOrFinitelyPresentedModuleRep.)
  
    Code  
    DeclareRepresentation( "IsFinitelyPresentedSubmoduleRep",
            IsFinitelyPresentedModuleOrSubmoduleRep and
            IsStaticFinitelyPresentedSubobjectRep and
            IsHomalgRingOrFinitelyPresentedModuleRep,
            [ "map_having_subobject_as_its_image" ] );
  
  
  
  7.2 Modules: Constructors
  
  7.2-1 LeftPresentation
  
  LeftPresentation( mat )  operation
  Returns:  a homalg module
  
  This  constructor  returns the finitely presented left module with relations
  given by the rows of the homalg matrix mat.
  
    Example  
    gap> ZZ := HomalgRingOfIntegers( );;
    gap> M := HomalgMatrix( "[ \
    > 2, 3, 4, \
    > 5, 6, 7  \
    > ]", 2, 3, ZZ );
    <A 2 x 3 matrix over an internal ring>
    gap> M := LeftPresentation( M );
    <A non-torsion left module presented by 2 relations for 3 generators>
    gap> Display( M );
    [ [  2,  3,  4 ],
      [  5,  6,  7 ] ]
    
    Cokernel of the map
    
    Z^(1x2) --> Z^(1x3),
    
    currently represented by the above matrix
    gap> ByASmallerPresentation( M );
    <A rank 1 left module presented by 1 relation for 2 generators>
    gap> Display( last );
    Z/< 3 > + Z^(1 x 1)
  
  
  7.2-2 RightPresentation
  
  RightPresentation( mat )  operation
  Returns:  a homalg module
  
  This  constructor returns the finitely presented right module with relations
  given by the columns of the homalg matrix mat.
  
    Example  
    gap> ZZ := HomalgRingOfIntegers( );;
    gap> M := HomalgMatrix( "[ \
    > 2, 3, 4, \
    > 5, 6, 7  \
    > ]", 2, 3, ZZ );
    <A 2 x 3 matrix over an internal ring>
    gap> M := RightPresentation( M );
    <A right module on 2 generators satisfying 3 relations>
    gap> ByASmallerPresentation( M );
    <A cyclic torsion right module on a cyclic generator satisfying 1 relation>
    gap> Display( last );
    Z/< 3 >
  
  
  7.2-3 HomalgFreeLeftModule
  
  HomalgFreeLeftModule( r, R )  operation
  Returns:  a homalg module
  
  This  constructor  returns a free left module of rank r over the homalg ring
  R.
  
    Example  
    gap> ZZ := HomalgRingOfIntegers( );;
    gap> F := HomalgFreeLeftModule( 1, ZZ );
    <A free left module of rank 1 on a free generator>
    gap> 1 * ZZ;
    <The free left module of rank 1 on a free generator>
    gap> F := HomalgFreeLeftModule( 2, ZZ );
    <A free left module of rank 2 on free generators>
    gap> 2 * ZZ;
    <A free left module of rank 2 on free generators>
  
  
  7.2-4 HomalgFreeRightModule
  
  HomalgFreeRightModule( r, R )  operation
  Returns:  a homalg module
  
  This  constructor returns a free right module of rank r over the homalg ring
  R.
  
    Example  
    gap> ZZ := HomalgRingOfIntegers( );;
    gap> F := HomalgFreeRightModule( 1, ZZ );
    <A free right module of rank 1 on a free generator>
    gap> ZZ * 1;
    <The free right module of rank 1 on a free generator>
    gap> F := HomalgFreeRightModule( 2, ZZ );
    <A free right module of rank 2 on free generators>
    gap> ZZ * 2;
    <A free right module of rank 2 on free generators>
  
  
  7.2-5 HomalgZeroLeftModule
  
  HomalgZeroLeftModule( r, R )  operation
  Returns:  a homalg module
  
  This  constructor  returns a zero left module of rank r over the homalg ring
  R.
  
    Example  
    gap> ZZ := HomalgRingOfIntegers( );;
    gap> F := HomalgZeroLeftModule( ZZ );
    <A zero left module>
    gap> 0 * ZZ;
    <The zero left module>
  
  
  7.2-6 HomalgZeroRightModule
  
  HomalgZeroRightModule( r, R )  operation
  Returns:  a homalg module
  
  This  constructor returns a zero right module of rank r over the homalg ring
  R.
  
    Example  
    gap> ZZ := HomalgRingOfIntegers( );;
    gap> F := HomalgZeroRightModule( ZZ );
    <A zero right module>
    gap> ZZ * 0;
    <The zero right module>
  
  
  7.2-7 \*
  
  \*( R, M )  operation
  \*( M, R )  operation
  Returns:  a homalg module
  
  Transfers  the  S-module  M over the homalg ring R. This works only in three
  cases:
  
  1   S is a subring of R.
  
  2   R is a residue class ring of S constructed using /.
  
  3   R  is  a  subring  of  S  and  the  entries  of  the current matrix of
        S-relations of M lie in R.
  
  CAUTION: So it is not suited for general base change.
  
    Example  
    gap> ZZ := HomalgRingOfIntegers( );
    Z
    gap> Display( ZZ );
    <An internal ring>
    gap> Z4 := ZZ / 4;
    Z/( 4 )
    gap> Display( Z4 );
    <A residue class ring>
    gap> M := HomalgDiagonalMatrix( [ 2 .. 4 ], ZZ );
    <An unevaluated diagonal 3 x 3 matrix over an internal ring>
    gap> M := LeftPresentation( M );
    <A torsion left module presented by 3 relations for 3 generators>
    gap> Display( M );
    Z/< 2 > + Z/< 3 > + Z/< 4 >
    gap> M;
    <A torsion left module presented by 3 relations for 3 generators>
    gap> N := Z4 * M; ## or N := M * Z4;
    <A non-torsion left module presented by 2 relations for 3 generators>
    gap> ByASmallerPresentation( N );
    <A non-torsion left module presented by 1 relation for 2 generators>
    gap> Display( N );
    Z/( 4 )/< |[ 2 ]| > + Z/( 4 )^(1 x 1)
    gap> N;
    <A non-torsion left module presented by 1 relation for 2 generators>
  
  
    Example  
    gap> ZZ := HomalgRingOfIntegers( );
    Z
    gap> M := HomalgMatrix( "[ \
    > 2, 3, 4, \
    > 5, 6, 7  \
    > ]", 2, 3, ZZ );
    <A 2 x 3 matrix over an internal ring>
    gap> M := LeftPresentation( M );
    <A non-torsion left module presented by 2 relations for 3 generators>
    gap> Z4 := ZZ / 4;
    Z/( 4 )
    gap> Display( Z4 );
    <A residue class ring>
    gap> M4 := Z4 * M;
    <A non-torsion left module presented by 2 relations for 3 generators>
    gap> Display( M4 );
    [ [  2,  3,  4 ],
      [  5,  6,  7 ] ]
    
    modulo [ 4 ]
    
    Cokernel of the map
    
    Z/( 4 )^(1x2) --> Z/( 4 )^(1x3),
    
    currently represented by the above matrix
    gap> d := Resolution( 2, M4 );
    <A right acyclic complex containing 2 morphisms of left modules at degrees 
    [ 0 .. 2 ]>
    gap> dd := Hom( d, Z4 );
    <A cocomplex containing 2 morphisms of right modules at degrees [ 0 .. 2 ]>
    gap> DD := Resolution( 2, dd );
    <A cocomplex containing 2 morphisms of right complexes at degrees [ 0 .. 2 ]>
    gap> D := Hom( DD, Z4 );
    <A complex containing 2 morphisms of left cocomplexes at degrees [ 0 .. 2 ]>
    gap> C := ZZ * D;
    <A "complex" containing 2 morphisms of left cocomplexes at degrees [ 0 .. 2 ]>
    gap> LowestDegreeObject( C );
    <A "cocomplex" containing 2 morphisms of left modules at degrees [ 0 .. 2 ]>
    gap> Display( last );
    -------------------------
    at cohomology degree: 2
    0
    ------------^------------
    (an empty 1 x 0 matrix)
    
    the map is currently represented by the above 1 x 0 matrix
    -------------------------
    at cohomology degree: 1
    Z/< 4 > 
    ------------^------------
    [ [  0 ],
      [  1 ],
      [  2 ],
      [  1 ] ]
    
    the map is currently represented by the above 4 x 1 matrix
    -------------------------
    at cohomology degree: 0
    Z/< 4 > + Z/< 4 > + Z/< 4 > + Z/< 4 > 
    -------------------------
  
  
  7.2-8 Subobject
  
  Subobject( mat, M )  operation
  Returns:  a homalg submodule
  
  This  constructor returns the finitely generated left/right submodule of the
  homalg  module  M  with  generators  given by the rows/columns of the homalg
  matrix mat.
  
  7.2-9 Subobject
  
  Subobject( gens, M )  operation
  Returns:  a homalg submodule
  
  This  constructor returns the finitely generated left/right submodule of the
  homalg  cyclic  left/right  module M with generators given by the entries of
  the list gens.
  
  7.2-10 LeftSubmodule
  
  LeftSubmodule( mat )  operation
  Returns:  a homalg submodule
  
  This   constructor  returns  the  finitely  generated  left  submodule  with
  generators given by the rows of the homalg matrix mat.
  
    Code  
    InstallMethod( LeftSubmodule,
            "constructor for homalg submodules",
            [ IsHomalgMatrix ],
            
      function( gen )
        local R;
        
        R := HomalgRing( gen );
        
        return Subobject( gen, NrColumns( gen ) * R );
        
    end );
  
  
    Example  
    gap> Z4 := HomalgRingOfIntegers( ) / 4;
    Z/( 4 )
    gap> I := HomalgMatrix( "[ 2 ]", 1, 1, Z4 );
    <A 1 x 1 matrix over a residue class ring>
    gap> I := LeftSubmodule( I );
    <A principal torsion-free (left) ideal given by a cyclic generator>
    gap> IsFree( I );
    false
    gap> I;
    <A principal reflexive non-projective (left) ideal given by a cyclic generator\
    >
  
  
  7.2-11 RightSubmodule
  
  RightSubmodule( mat )  operation
  Returns:  a homalg submodule
  
  This  constructor  returns  the  finitely  generated  right  submodule  with
  generators given by the columns of the homalg matrix mat.
  
    Code  
    InstallMethod( RightSubmodule,
            "constructor for homalg submodules",
            [ IsHomalgMatrix ],
            
      function( gen )
        local R;
        
        R := HomalgRing( gen );
        
        return Subobject( gen, R * NrRows( gen ) );
        
    end );
  
  
    Example  
    gap> Z4 := HomalgRingOfIntegers( ) / 4;
    Z/( 4 )
    gap> I := HomalgMatrix( "[ 2 ]", 1, 1, Z4 );
    <A 1 x 1 matrix over a residue class ring>
    gap> I := RightSubmodule( I );
    <A principal torsion-free (right) ideal given by a cyclic generator>
    gap> IsFree( I );
    false
    gap> I;
    <A principal reflexive non-projective (right) ideal given by a cyclic generato\
    r>
  
  
  
  7.3 Modules: Properties
  
  7.3-1 IsCyclic
  
  IsCyclic( M )  property
  Returns:  true or false
  
  Check if the homalg module M is cyclic.
  
  7.3-2 IsHolonomic
  
  IsHolonomic( M )  property
  Returns:  true or false
  
  Check if the homalg module M is holonomic.
  
  7.3-3 IsReduced
  
  IsReduced( M )  property
  Returns:  true or false
  
  Check if the homalg module M is reduced.
  
  7.3-4 IsPrimeIdeal
  
  IsPrimeIdeal( J )  property
  Returns:  true or false
  
  Check  if  the  homalg  submodule  J  is  a  prime ideal. The ring has to be
  commutative.
  (no method installed)
  
  7.3-5 IsPrimeModule
  
  IsPrimeModule( M )  property
  Returns:  true or false
  
  Check if the homalg module M is prime.
  
  For   more  properties  see  the  corresponding  section  'homalg:  Objects:
  Properties') in the documentation of the homalg package.
  
  
  7.4 Modules: Attributes
  
  7.4-1 ResidueClassRing
  
  ResidueClassRing( J )  attribute
  Returns:  a homalg ring
  
  In  case  J  was  defined  as a (left/right) ideal of the ring R the residue
  class ring R/J is returned.
  
  7.4-2 PrimaryDecomposition
  
  PrimaryDecomposition( J )  attribute
  Returns:  a list
  
  The primary decomposition of the ideal J. The ring has to be commutative.
  (no method installed)
  
  7.4-3 RadicalDecomposition
  
  RadicalDecomposition( J )  attribute
  Returns:  a list
  
  The  prime  decomposition  of the radical of the ideal J. The ring has to be
  commutative.
  (no method installed)
  
  7.4-4 ModuleOfKaehlerDifferentials
  
  ModuleOfKaehlerDifferentials( R )  attribute
  Returns:  a homalg module
  
  The module of Kaehler differentials of the (residue class ring) R.
  (method installed in package GradedModules)
  
  7.4-5 RadicalSubobject
  
  RadicalSubobject( M )  property
  Returns:  a function
  
  M is a homalg module.
  
  7.4-6 SymmetricAlgebra
  
  SymmetricAlgebra( M )  attribute
  Returns:  a homalg ring
  
  The symmetric algebra of the module M.
  
  7.4-7 ExteriorAlgebra
  
  ExteriorAlgebra( M )  attribute
  Returns:  a homalg ring
  
  The exterior algebra of the module M.
  
  7.4-8 ElementaryDivisors
  
  ElementaryDivisors( M )  attribute
  Returns:  a list of ring elements
  
  The list of elementary divisors of the homalg module M, in case they exist.
  (no method installed)
  
  7.4-9 FittingIdeal
  
  FittingIdeal( M )  attribute
  Returns:  a list
  
  The Fitting ideal of M.
  
  7.4-10 NonFlatLocus
  
  NonFlatLocus( M )  attribute
  Returns:  a list
  
  The non flat locus of M.
  
  7.4-11 LargestMinimalNumberOfLocalGenerators
  
  LargestMinimalNumberOfLocalGenerators( M )  attribute
  Returns:  a nonnegative integer
  
  The minimal number of local generators of the module M.
  
  7.4-12 CoefficientsOfUnreducedNumeratorOfHilbertPoincareSeries
  
  CoefficientsOfUnreducedNumeratorOfHilbertPoincareSeries( M )  attribute
  Returns:  a list of integers
  
  M is a homalg module.
  
  7.4-13 CoefficientsOfNumeratorOfHilbertPoincareSeries
  
  CoefficientsOfNumeratorOfHilbertPoincareSeries( M )  attribute
  Returns:  a list of integers
  
  M is a homalg module.
  
  7.4-14 UnreducedNumeratorOfHilbertPoincareSeries
  
  UnreducedNumeratorOfHilbertPoincareSeries( M )  attribute
  Returns:  a univariate polynomial with rational coefficients
  
  M is a homalg module.
  
  7.4-15 NumeratorOfHilbertPoincareSeries
  
  NumeratorOfHilbertPoincareSeries( M )  attribute
  Returns:  a univariate polynomial with rational coefficients
  
  M is a homalg module.
  
  7.4-16 HilbertPoincareSeries
  
  HilbertPoincareSeries( M )  attribute
  Returns:  a univariate rational function with rational coefficients
  
  M is a homalg module.
  
  7.4-17 AffineDegree
  
  AffineDegree( M )  attribute
  Returns:  a nonnegative integer
  
  M is a homalg module.
  
  7.4-18 DataOfHilbertFunction
  
  DataOfHilbertFunction( M )  property
  Returns:  a function
  
  M is a homalg module.
  
  7.4-19 HilbertFunction
  
  HilbertFunction( M )  property
  Returns:  a function
  
  M is a homalg module.
  
  7.4-20 IndexOfRegularity
  
  IndexOfRegularity( M )  property
  Returns:  a function
  
  M is a homalg module.
  
  For   more  attributes  see  the  corresponding  section  'homalg:  Objects:
  Attributes') in the documentation of the homalg package.
  
  
  7.5 Modules: Operations and Functions
  
  7.5-1 HomalgRing
  
  HomalgRing( M )  operation
  Returns:  a homalg ring
  
  The homalg ring of the homalg module M.
  
    Example  
    gap> ZZ := HomalgRingOfIntegers( );
    Z
    gap> M := ZZ * 4;
    <A free right module of rank 4 on free generators>
    gap> R := HomalgRing( M );
    Z
    gap> IsIdenticalObj( R, ZZ );
    true
  
  
  7.5-2 ByASmallerPresentation
  
  ByASmallerPresentation( M )  method
  Returns:  a homalg module
  
  Use  different  strategies  to  reduce  the presentation of the given homalg
  module  M.  This  method performs side effects on its argument M and returns
  it.
  
    Example  
    gap> ZZ := HomalgRingOfIntegers( );;
    gap> M := HomalgMatrix( "[ \
    > 2, 3, 4, \
    > 5, 6, 7  \
    > ]", 2, 3, ZZ );
    <A 2 x 3 matrix over an internal ring>
    gap> M := LeftPresentation( M );
    <A non-torsion left module presented by 2 relations for 3 generators>
    gap> Display( M );
    [ [  2,  3,  4 ],
      [  5,  6,  7 ] ]
    
    Cokernel of the map
    
    Z^(1x2) --> Z^(1x3),
    
    currently represented by the above matrix
    gap> ByASmallerPresentation( M );
    <A rank 1 left module presented by 1 relation for 2 generators>
    gap> Display( last );
    Z/< 3 > + Z^(1 x 1)
    gap> SetsOfGenerators( M );
    <A set containing 2 sets of generators of a homalg module>
    gap> SetsOfRelations( M );
    <A set containing 2 sets of relations of a homalg module>
    gap> M;
    <A rank 1 left module presented by 1 relation for 2 generators>
    gap> SetPositionOfTheDefaultPresentation( M, 1 );
    gap> M;
    <A rank 1 left module presented by 2 relations for 3 generators>
  
  
  7.5-3 \*
  
  \*( J, M )  operation
  Returns:  a homalg submodule
  
  Compute the submodule JM (resp. MJ) of the given left (resp. right) R-module
  M, where J is a left (resp. right) ideal in R.
  
  7.5-4 SubobjectQuotient
  
  SubobjectQuotient( K, J )  operation
  Returns:  a homalg ideal
  
  Compute  the  submodule  quotient  ideal  K:J of the submodules K and J of a
  common R-module M.