chapE.txt

  
  E Debugging MatricesForHomalg
  
  Beside  the  GAP builtin debugging facilities (--> 'Reference: Debugging and
  Profiling  Facilities')  MatricesForHomalg  provides  two  ways to debug the
  computations.
  
  
  E.1 Increase the assertion level
  
  MatricesForHomalg  comes  with  numerous  builtin assertion checks. They are
  activated if the user increases the assertion level using
  SetAssertionLevel( level );
  (-->  'Reference:  SetAssertionLevel'),  where  level  is  one of the values
  below:
  
        level │ description                                                             
        ──────┼──────────────────────────────────────────────────────────────────────  
              │                                                                         
        0     │ no assertion checks whatsoever                                          
              │                                                                         
        4     │ assertions about basic matrix operations are checked (--> Appendix A)   
              │ (these are among the operations often delegated to external systems)    
              │                                                                         
        ──────┴──────────────────────────────────────────────────────────────────────  
  
  In  particular,  if  MatricesForHomalg  delegates  matrix  operations  to an
  external   system   then   SetAssertionLevel(  4  );  can  be  used  to  let
  MatricesForHomalg debug the external system.
  Below  you can find the record of the available level-4 assertions, which is
  a GAP-component of every homalg ring. Each assertion can thus be overwritten
  by package developers or even ordinary users.
  
    Code  
    asserts :=
      rec(
          BasisOfRowModule :=
            function( B ) return ( NrRows( B ) = 0 ) = IsZero( B ); end,
          
          BasisOfColumnModule :=
            function( B ) return ( NrColumns( B ) = 0 ) = IsZero( B ); end,
          
          BasisOfRowsCoeff :=
            function( B, T, M ) return B = T * M; end,
          
          BasisOfColumnsCoeff :=
            function( B, M, T ) return B = M * T; end,
          
          DecideZeroRows_Effectively :=
            function( M, A, B ) return M = DecideZeroRows( A, B ); end,
          
          DecideZeroColumns_Effectively :=
            function( M, A, B ) return M = DecideZeroColumns( A, B ); end,
          
          DecideZeroRowsEffectively :=
            function( M, A, T, B ) return M = A + T * B; end,
          
          DecideZeroColumnsEffectively :=
            function( M, A, B, T ) return M = A + B * T; end,
          
          DecideZeroRowsWRTNonBasis :=
            function( B )
              local R;
              R := HomalgRing( B );
              if not ( HasIsBasisOfRowsMatrix( B ) and
                       IsBasisOfRowsMatrix( B ) ) and
                 IsBound( R!.DecideZeroWRTNonBasis ) then
                  if R!.DecideZeroWRTNonBasis = "warn" then
                      Info( InfoWarning, 1,
                            "about to reduce with respect to a matrix",
                            "with IsBasisOfRowsMatrix not set to true" );
                  elif R!.DecideZeroWRTNonBasis = "error" then
                      Error( "about to reduce with respect to a matrix",
                             "with IsBasisOfRowsMatrix not set to true\n" );
                  fi;
              fi;
            end,
          
          DecideZeroColumnsWRTNonBasis :=
            function( B )
              local R;
              R := HomalgRing( B );
              if not ( HasIsBasisOfColumnsMatrix( B ) and
                       IsBasisOfColumnsMatrix( B ) ) and
                 IsBound( R!.DecideZeroWRTNonBasis ) then
                  if R!.DecideZeroWRTNonBasis = "warn" then
                      Info( InfoWarning, 1,
                            "about to reduce with respect to a matrix",
                            "with IsBasisOfColumnsMatrix not set to true" );
                  elif R!.DecideZeroWRTNonBasis = "error" then
                      Error( "about to reduce with respect to a matrix",
                             "with IsBasisOfColumnsMatrix not set to true\n" );
                  fi;
              fi;
            end,
          
          ReducedBasisOfRowModule :=
            function( M, B )
              return GenerateSameRowModule( B, BasisOfRowModule( M ) );
            end,
          
          ReducedBasisOfColumnModule :=
            function( M, B )
              return GenerateSameColumnModule( B, BasisOfColumnModule( M ) );
            end,
          
          ReducedSyzygiesGeneratorsOfRows :=
            function( M, S )
              return GenerateSameRowModule( S, SyzygiesGeneratorsOfRows( M ) );
            end,
          
          ReducedSyzygiesGeneratorsOfColumns :=
            function( M, S )
              return GenerateSameColumnModule( S, SyzygiesGeneratorsOfColumns( M ) );
            end,
          
         );
  
  
  
  E.2 Using homalgMode
  
  E.2-1 homalgMode
  
  homalgMode( str[, str2] )  method
  
  This  function  sets  different  modes which influence how much of the basic
  matrix  operations  and  the  logical  matrix  methods  become  visible (-->
  Appendices A, C). Handling the string str is not case-sensitive. If a second
  string str2 is given, then homalgMode( str2 ) is invoked at the end. In case
  you  let  homalg  delegate  matrix  operations to an external system the you
  might also want to check homalgIOMode in the HomalgToCAS package manual.
  
        str │ str (long form) │ mode description                                                      
        ────┼─────────────────┼────────────────────────────────────────────────────────────────────  
            │                 │                                                                       
        ""  │       ""        │ the default mode, i.e. the computation protocol won't be visible      
            │                 │ (homalgMode( ) is a short form for homalgMode( "" ))                  
            │                 │                                                                       
        "b" │     "basic"     │ make the basic matrix operations visible + homalgMode( "logic" )      
            │                 │                                                                       
        "d" │     "debug"     │ same as "basic" but also makes Row/ColumnReducedEchelonForm visible   
            │                 │                                                                       
        "l" │     "logic"     │ make the logical methods in LIMAT and COLEM visible                   
            │                 │                                                                       
        ────┴─────────────────┴────────────────────────────────────────────────────────────────────  
  
  All  modes  other than the "default"-mode only set their specific values and
  leave  the  other  values  untouched,  which  allows  combining them to some
  extent.  This  also  means  that in order to get from one mode to a new mode
  (without  the  aim to combine them) one needs to reset to the "default"-mode
  first. This can be done using homalgMode( "", new_mode );
  
    Code  
    InstallGlobalFunction( homalgMode,
      function( arg )
        local nargs, mode, s;
        
        nargs := Length( arg );
        
        if nargs = 0 or ( IsString( arg[1] ) and arg[1] = "" ) then
            mode := "default";
        elif IsString( arg[1] ) then	## now we know, the string is not empty
            s := arg[1];
            if LowercaseString( s{[1]} ) = "b" then
                mode := "basic";
            elif LowercaseString( s{[1]} ) = "d" then
                mode := "debug";
            elif LowercaseString( s{[1]} ) = "l" then
                mode := "logic";
            else
                mode := "";
            fi;
        else
            Error( "the first argument must be a string\n" );
        fi;
        
        if mode = "default" then
            HOMALG_MATRICES.color_display := false;
            for s in HOMALG_MATRICES.matrix_logic_infolevels do
                SetInfoLevel( s, 1 );
            od;
            SetInfoLevel( InfoHomalgBasicOperations, 1 );
        elif mode = "basic" then
            SetInfoLevel( InfoHomalgBasicOperations, 3 );
            homalgMode( "logic" );
        elif mode = "debug" then
            SetInfoLevel( InfoHomalgBasicOperations, 4 );
            homalgMode( "logic" );
        elif mode = "logic" then
            HOMALG_MATRICES.color_display := true;
            for s in HOMALG_MATRICES.matrix_logic_infolevels do
                SetInfoLevel( s, 2 );
            od;
        fi;
        
        if nargs > 1 and IsString( arg[2] ) then
            homalgMode( arg[2] );
        fi;
        
    end );