D The subpackage ResidueClassRingForHomalg as a sample ring package
  
  
  D.1 The Mandatory Basic Operations
  
  D.1-1 BasisOfRowModule
  
  BasisOfRowModule( M )  function
  Returns:  a homalg matrix over the ambient ring
  
    Code  
    BasisOfRowModule :=
      function( M )
        local Mrel;
        
        Mrel := UnionOfRows( M );
        
        Mrel := HomalgResidueClassMatrix(
                        BasisOfRowModule( Mrel ), HomalgRing( M ) );
        
        return GetRidOfObsoleteRows( Mrel );
        
      end,
  
  
  D.1-2 BasisOfColumnModule
  
  BasisOfColumnModule( M )  function
  Returns:  a homalg matrix over the ambient ring
  
    Code  
    BasisOfColumnModule :=
      function( M )
        local Mrel;
        
        Mrel := UnionOfColumns( M );
        
        Mrel := HomalgResidueClassMatrix(
                        BasisOfColumnModule( Mrel ), HomalgRing( M ) );
        
        return GetRidOfObsoleteColumns( Mrel );
        
      end,
  
  
  D.1-3 DecideZeroRows
  
  DecideZeroRows( A, B )  function
  Returns:  a homalg matrix over the ambient ring
  
    Code  
    DecideZeroRows :=
      function( A, B )
        local Brel;
        
        Brel := UnionOfRows( B );
        
        Brel := BasisOfRowModule( Brel );
        
        return HomalgResidueClassMatrix(
                       DecideZeroRows( Eval( A ), Brel ), HomalgRing( A ) );
        
      end,
  
  
  D.1-4 DecideZeroColumns
  
  DecideZeroColumns( A, B )  function
  Returns:  a homalg matrix over the ambient ring
  
    Code  
    DecideZeroColumns :=
      function( A, B )
        local Brel;
        
        Brel := UnionOfColumns( B );
        
        Brel := BasisOfColumnModule( Brel );
        
        return HomalgResidueClassMatrix(
                       DecideZeroColumns( Eval( A ), Brel ), HomalgRing( A ) );
        
      end,
  
  
  D.1-5 SyzygiesGeneratorsOfRows
  
  SyzygiesGeneratorsOfRows( M )  function
  Returns:  a homalg matrix over the ambient ring
  
    Code  
    SyzygiesGeneratorsOfRows :=
      function( M )
        local R, ring_rel, rel, S;
        
        R := HomalgRing( M );
        
        ring_rel := RingRelations( R );
        
        rel := MatrixOfRelations( ring_rel );
        
        if IsHomalgRingRelationsAsGeneratorsOfRightIdeal( ring_rel ) then
            rel := Involution( rel );
        fi;
        
        rel := DiagMat( ListWithIdenticalEntries( NrColumns( M ), rel ) );
        
        S := SyzygiesGeneratorsOfRows( Eval( M ), rel );
        
        S := HomalgResidueClassMatrix( S, R );
        
        S := GetRidOfObsoleteRows( S );
        
        if IsZero( S ) then
            
            SetIsLeftRegular( M, true );
            
        fi;
        
        return S;
        
      end,
  
  
  D.1-6 SyzygiesGeneratorsOfColumns
  
  SyzygiesGeneratorsOfColumns( M )  function
  Returns:  a homalg matrix over the ambient ring
  
    Code  
    SyzygiesGeneratorsOfColumns :=
      function( M )
        local R, ring_rel, rel, S;
        
        R := HomalgRing( M );
        
        ring_rel := RingRelations( R );
        
        rel := MatrixOfRelations( ring_rel );
        
        if IsHomalgRingRelationsAsGeneratorsOfLeftIdeal( ring_rel ) then
            rel := Involution( rel );
        fi;
        
        rel := DiagMat( ListWithIdenticalEntries( NrRows( M ), rel ) );
        
        S := SyzygiesGeneratorsOfColumns( Eval( M ), rel );
        
        S := HomalgResidueClassMatrix( S, R );
        
        S := GetRidOfObsoleteColumns( S );
        
        if IsZero( S ) then
            
            SetIsRightRegular( M, true );
            
        fi;
        
        return S;
        
      end,
  
  
  D.1-7 BasisOfRowsCoeff
  
  BasisOfRowsCoeff( M, T )  function
  Returns:  a homalg matrix over the ambient ring
  
    Code  
    BasisOfRowsCoeff :=
      function( M, T )
        local Mrel, TT, bas, nz;
        
        Mrel := UnionOfRows( M );
        
        TT := HomalgVoidMatrix( HomalgRing( Mrel ) );
        
        bas := BasisOfRowsCoeff( Mrel, TT );
        
        bas := HomalgResidueClassMatrix( bas, HomalgRing( M ) );
        
        nz := NonZeroRows( bas );
        
        SetEval( T, CertainRows( CertainColumns( TT, [ 1 .. NrRows( M ) ] ), nz ) );
        
        ResetFilterObj( T, IsVoidMatrix );
        
        ## the generic BasisOfRowsCoeff will assume that
        ## ( NrRows( B ) = 0 ) = IsZero( B )
        return CertainRows( bas, nz );
        
      end,
  
  
  D.1-8 BasisOfColumnsCoeff
  
  BasisOfColumnsCoeff( M, T )  function
  Returns:  a homalg matrix over the ambient ring
  
    Code  
    BasisOfColumnsCoeff :=
      function( M, T )
        local Mrel, TT, bas, nz;
        
        Mrel := UnionOfColumns( M );
        
        TT := HomalgVoidMatrix( HomalgRing( Mrel ) );
        
        bas := BasisOfColumnsCoeff( Mrel, TT );
        
        bas := HomalgResidueClassMatrix( bas, HomalgRing( M ) );
        
        nz := NonZeroColumns( bas );
        
        SetEval( T, CertainColumns( CertainRows( TT, [ 1 .. NrColumns( M ) ] ), nz ) );
        
        ResetFilterObj( T, IsVoidMatrix );
        
        ## the generic BasisOfColumnsCoeff will assume that
        ## ( NrColumns( B ) = 0 ) = IsZero( B )
        return CertainColumns( bas, nz );
        
      end,
  
  
  D.1-9 DecideZeroRowsEffectively
  
  DecideZeroRowsEffectively( A, B, T )  function
  Returns:  a homalg matrix over the ambient ring
  
    Code  
    DecideZeroRowsEffectively :=
      function( A, B, T )
        local Brel, TT, red;
        
        Brel := UnionOfRows( B );
        
        TT := HomalgVoidMatrix( HomalgRing( Brel ) );
        
        red := DecideZeroRowsEffectively( Eval( A ), Brel, TT );
        
        SetEval( T, CertainColumns( TT, [ 1 .. NrRows( B ) ] ) );
        
        ResetFilterObj( T, IsVoidMatrix );
        
        return HomalgResidueClassMatrix( red, HomalgRing( A ) );
        
      end,
  
  
  D.1-10 DecideZeroColumnsEffectively
  
  DecideZeroColumnsEffectively( A, B, T )  function
  Returns:  a homalg matrix over the ambient ring
  
    Code  
    DecideZeroColumnsEffectively :=
      function( A, B, T )
        local Brel, TT, red;
        
        Brel := UnionOfColumns( B );
        
        TT := HomalgVoidMatrix( HomalgRing( Brel ) );
        
        red := DecideZeroColumnsEffectively( Eval( A ), Brel, TT );
        
        SetEval( T, CertainRows( TT, [ 1 .. NrColumns( B ) ] ) );
        
        ResetFilterObj( T, IsVoidMatrix );
        
        return HomalgResidueClassMatrix( red, HomalgRing( A ) );
        
      end,
  
  
  D.1-11 RelativeSyzygiesGeneratorsOfRows
  
  RelativeSyzygiesGeneratorsOfRows( M, M2 )  function
  Returns:  a homalg matrix over the ambient ring
  
    Code  
    RelativeSyzygiesGeneratorsOfRows :=
      function( M, M2 )
        local M2rel, S;
        
        M2rel := UnionOfRows( M2 );
        
        S := SyzygiesGeneratorsOfRows( Eval( M ), M2rel );
        
        S := HomalgResidueClassMatrix( S, HomalgRing( M ) );
        
        S := GetRidOfObsoleteRows( S );
        
        if IsZero( S ) then
            
            SetIsLeftRegular( M, true );
            
        fi;
        
        return S;
        
      end,
  
  
  D.1-12 RelativeSyzygiesGeneratorsOfColumns
  
  RelativeSyzygiesGeneratorsOfColumns( M, M2 )  function
  Returns:  a homalg matrix over the ambient ring
  
    Code  
    RelativeSyzygiesGeneratorsOfColumns :=
      function( M, M2 )
        local M2rel, S;
        
        M2rel := UnionOfColumns( M2 );
        
        S := SyzygiesGeneratorsOfColumns( Eval( M ), M2rel );
        
        S := HomalgResidueClassMatrix( S, HomalgRing( M ) );
        
        S := GetRidOfObsoleteColumns( S );
        
        if IsZero( S ) then
            
            SetIsRightRegular( M, true );
            
        fi;
        
        return S;
        
      end,
  
  
  
  D.2 The Mandatory Tool Operations
  
  Here  we  list those matrix operations for which homalg provides no fallback
  method.
  
  D.2-1 InitialMatrix
  
  InitialMatrix(  )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> InitialMatrix (B.1-1))
  
    Code  
    InitialMatrix := C -> HomalgInitialMatrix(
                          NrRows( C ), NrColumns( C ), AmbientRing( HomalgRing( C ) ) ),
  
  
  D.2-2 InitialIdentityMatrix
  
  InitialIdentityMatrix(  )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> InitialIdentityMatrix (B.1-2))
  
    Code  
    InitialIdentityMatrix := C -> HomalgInitialIdentityMatrix(
            NrRows( C ), AmbientRing( HomalgRing( C ) ) ),
  
  
  D.2-3 ZeroMatrix
  
  ZeroMatrix(  )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> ZeroMatrix (B.1-3))
  
    Code  
    ZeroMatrix := C -> HomalgZeroMatrix(
                          NrRows( C ), NrColumns( C ), AmbientRing( HomalgRing( C ) ) ),
  
  
  D.2-4 IdentityMatrix
  
  IdentityMatrix(  )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> IdentityMatrix (B.1-4))
  
    Code  
    IdentityMatrix := C -> HomalgIdentityMatrix(
            NrRows( C ), AmbientRing( HomalgRing( C ) ) ),
  
  
  D.2-5 Involution
  
  Involution(  )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> Involution (B.1-5))
  
    Code  
    Involution :=
      function( M )
        local N, R;
        
        N := Involution( Eval( M ) );
        
        R := HomalgRing( N );
        
        if not ( HasIsCommutative( R ) and IsCommutative( R ) and
                 HasIsReducedModuloRingRelations( M ) and
                 IsReducedModuloRingRelations( M ) ) then
            
            ## reduce the matrix N w.r.t. the ring relations
            N := DecideZero( N, HomalgRing( M ) );
        fi;
        
        return N;
        
      end,
  
  
  D.2-6 CertainRows
  
  CertainRows(  )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> CertainRows (B.1-6))
  
    Code  
    CertainRows :=
      function( M, plist )
        local N;
        
        N := CertainRows( Eval( M ), plist );
        
        if not ( HasIsReducedModuloRingRelations( M ) and
                 IsReducedModuloRingRelations( M ) ) then
            
            ## reduce the matrix N w.r.t. the ring relations
            N := DecideZero( N, HomalgRing( M ) );
        fi;
        
        return N;
        
      end,
  
  
  D.2-7 CertainColumns
  
  CertainColumns(  )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> CertainColumns (B.1-7))
  
    Code  
    CertainColumns :=
      function( M, plist )
        local N;
        
        N := CertainColumns( Eval( M ), plist );
        
        if not ( HasIsReducedModuloRingRelations( M ) and
                 IsReducedModuloRingRelations( M ) ) then
            
            ## reduce the matrix N w.r.t. the ring relations
            N := DecideZero( N, HomalgRing( M ) );
        fi;
        
        return N;
        
      end,
  
  
  D.2-8 UnionOfRows
  
  UnionOfRows(  )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> UnionOfRows (B.1-8))
  
    Code  
    UnionOfRows :=
      function( A, B )
        local N;
        
        N := UnionOfRows( Eval( A ), Eval( B ) );
        
        if not ForAll( [ A, B ], HasIsReducedModuloRingRelations and
                   IsReducedModuloRingRelations ) then
            
            ## reduce the matrix N w.r.t. the ring relations
            N := DecideZero( N, HomalgRing( A ) );
        fi;
        
        return N;
        
      end,
  
  
  D.2-9 UnionOfColumns
  
  UnionOfColumns(  )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> UnionOfColumns (B.1-9))
  
    Code  
    UnionOfColumns :=
      function( A, B )
        local N;
        
        N := UnionOfColumns( Eval( A ), Eval( B ) );
        
        if not ForAll( [ A, B ], HasIsReducedModuloRingRelations and
                   IsReducedModuloRingRelations ) then
            
            ## reduce the matrix N w.r.t. the ring relations
            N := DecideZero( N, HomalgRing( A ) );
        fi;
        
        return N;
        
      end,
  
  
  D.2-10 DiagMat
  
  DiagMat(  )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> DiagMat (B.1-10))
  
    Code  
    DiagMat :=
      function( e )
        local N;
        
        N := DiagMat( List( e, Eval ) );
        
        if not ForAll( e, HasIsReducedModuloRingRelations and
                   IsReducedModuloRingRelations ) then
            
            ## reduce the matrix N w.r.t. the ring relations
            N := DecideZero( N, HomalgRing( e[1] ) );
        fi;
        
        return N;
        
      end,
  
  
  D.2-11 KroneckerMat
  
  KroneckerMat(  )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> KroneckerMat (B.1-11))
  
    Code  
    KroneckerMat :=
      function( A, B )
        local N;
        
        N := KroneckerMat( Eval( A ), Eval( B ) );
        
        if not ForAll( [ A, B ], HasIsReducedModuloRingRelations and
                   IsReducedModuloRingRelations ) then
            
            ## reduce the matrix N w.r.t. the ring relations
            N := DecideZero( N, HomalgRing( A ) );
        fi;
        
        return N;
        
      end,
  
  
  D.2-12 MulMat
  
  MulMat(  )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> MulMat (B.1-12))
  
    Code  
    MulMat :=
      function( a, A )
        
        return DecideZero( EvalRingElement( a ) * Eval( A ), HomalgRing( A ) );
        
      end,
    MulMatRight :=
      function( A, a )
        
        return DecideZero( Eval( A ) * EvalRingElement( a ), HomalgRing( A ) );
        
      end,
  
  
  D.2-13 AddMat
  
  AddMat(  )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> AddMat (B.1-13))
  
    Code  
    AddMat :=
      function( A, B )
        
        return DecideZero( Eval( A ) + Eval( B ), HomalgRing( A ) );
        
      end,
  
  
  D.2-14 SubMat
  
  SubMat(  )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> SubMat (B.1-14))
  
    Code  
    SubMat :=
      function( A, B )
        
        return DecideZero( Eval( A ) - Eval( B ), HomalgRing( A ) );
        
      end,
  
  
  D.2-15 Compose
  
  Compose(  )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> Compose (B.1-15))
  
    Code  
    Compose :=
      function( A, B )
        
        return DecideZero( Eval( A ) * Eval( B ), HomalgRing( A ) );
        
      end,
  
  
  D.2-16 IsZeroMatrix
  
  IsZeroMatrix( M )  function
  Returns:  true or false
  
  (--> IsZeroMatrix (B.1-16))
  
    Code  
    IsZeroMatrix := M -> IsZero( DecideZero( Eval( M ), HomalgRing( M ) ) ),
  
  
  D.2-17 NrRows
  
  NrRows( C )  function
  Returns:  a nonnegative integer
  
  (--> NrRows (B.1-17))
  
    Code  
    NrRows := C -> NrRows( Eval( C ) ),
  
  
  D.2-18 NrColumns
  
  NrColumns( C )  function
  Returns:  a nonnegative integer
  
  (--> NrColumns (B.1-18))
  
    Code  
    NrColumns := C -> NrColumns( Eval( C ) ),
  
  
  D.2-19 Determinant
  
  Determinant( C )  function
  Returns:  an element of ambient homalg ring
  
  (--> Determinant (B.1-19))
  
    Code  
    Determinant := C -> DecideZero( Determinant( Eval( C ) ), HomalgRing( C ) ),
  
  
  
  D.3 Some of the Recommended Tool Operations
  
  Here  we  list  those  matrix  operations  for  which  homalg does provide a
  fallback  method.  But  specifying the below homalgTable functions increases
  the performance by replacing the fallback method.
  
  D.3-1 AreEqualMatrices
  
  AreEqualMatrices( A, B )  function
  Returns:  true or false
  
  (--> AreEqualMatrices (B.2-1))
  
    Code  
    AreEqualMatrices :=
      function( A, B )
        
        return IsZero( DecideZero( Eval( A ) - Eval( B ), HomalgRing( A ) ) );
        
      end,
  
  
  D.3-2 IsOne
  
  IsOne( M )  function
  Returns:  true or false
  
  (--> IsIdentityMatrix (B.2-2))
  
    Code  
    IsIdentityMatrix := M ->
              IsOne( DecideZero( Eval( M ), HomalgRing( M ) ) ),
  
  
  D.3-3 IsDiagonalMatrix
  
  IsDiagonalMatrix( M )  function
  Returns:  true or false
  
  (--> IsDiagonalMatrix (B.2-3))
  
    Code  
    IsDiagonalMatrix := M ->
              IsDiagonalMatrix( DecideZero( Eval( M ), HomalgRing( M ) ) ),
  
  
  D.3-4 ZeroRows
  
  ZeroRows( C )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> ZeroRows (B.2-4))
  
    Code  
    ZeroRows := C -> ZeroRows( DecideZero( Eval( C ), HomalgRing( C ) ) ),
  
  
  D.3-5 ZeroColumns
  
  ZeroColumns( C )  function
  Returns:  a homalg matrix over the ambient ring
  
  (--> ZeroColumns (B.2-5))
  
    Code  
    ZeroColumns := C -> ZeroColumns( DecideZero( Eval( C ), HomalgRing( C ) ) ),