chap15.txt

  
  15 Miscellaneous functions
  
  The  behaviour  of simpcomp can be changed by setting cetain global options.
  This can be achieved by the functions described in the following.
  
  
  15.1 simpcomp logging
  
  The  verbosity  of  the  output of information to the screen during calls to
  functions  of  the  package  simpcomp  can be controlled by setting the info
  level parameter via the function SCInfoLevel (15.1-1).
  
  15.1-1 SCInfoLevel
  
  SCInfoLevel( level )  function
  Returns:  true
  
  Sets  the logging verbosity of simpcomp. A level of 0 suppresses all output,
  a level of 1 lets simpcomp output normal running information, whereas levels
  of  2  and higher display verbose running information. Examples of functions
  using more verbose logging are bistellar flip-related functions.
  
    Example  
    gap> SCInfoLevel(3);
    true
    gap> c:=SCBdCrossPolytope(3);;
    gap> SCReduceComplex(c); 
    #I  round 0, move: [ [ 4, 5 ], [ 1, 2 ] ]
    F: [ 6, 12, 8 ]
    #I  round 1, move: [ [ 5 ], [ 1, 2, 3 ] ]
    F: [ 5, 9, 6 ]
    #I  round 1
    Reduced complex, F: [ 5, 9, 6 ]
    #I  round 2, move: [ [ 3 ], [ 1, 2, 6 ] ]
    F: [ 4, 6, 4 ]
    #I  round 2
    Reduced complex, F: [ 4, 6, 4 ]
    #I  SCReduceComplexEx: computed locally minimal complex after 3 rounds.
    [ true, [SimplicialComplex
        
         Properties known: Dim, FacetsEx, Name, Vertices.
        
         Name="unnamed complex 3"
         Dim=2
        
        /SimplicialComplex], 3 ]
  
  
  
  15.2 Email notification system
  
  simpcomp  comes with an email notification system that can be used for being
  notified of the progress of lengthy computations (such as reducing a complex
  via  bistellar  flips). See below for a description of the mail notification
  related functions. Note that this might not work on non-Unix systems.
  
  See  SCReduceComplexEx  (9.2-14)  for an example computation using the email
  notification system.
  
  15.2-1 SCMailClearPending
  
  SCMailClearPending(  )  function
  Returns:  nothing.
  
  Clears a pending mail message.
  
    Example  
     gap> SCMailClearPending();
     
     
  
  
  15.2-2 SCMailIsEnabled
  
  SCMailIsEnabled(  )  function
  Returns:  true or false upon success, fail otherwise.
  
  Returns true when the mail notification system of simpcomp is enabled, false
  otherwise. Default setting is false.
  
    Example  
     gap> SCMailSetAddress("johndoe@somehost"); #enables mail notification
     true
     gap> SCMailIsEnabled();
     true
     
  
  
  15.2-3 SCMailIsPending
  
  SCMailIsPending(  )  function
  Returns:  true or false upon success, fail otherwise.
  
  Returns  true  when  an  email  of the simpcomp email notification system is
  pending, false otherwise.
  
    Example  
     gap> SCMailIsPending();
     false
     
  
  
  15.2-4 SCMailSend
  
  SCMailSend( message[, starttime][, forcesend] )  function
  Returns:  true  when  the  message  was sent, false if it was not send, fail
            upon an error.
  
  Tries to send an email to the address specified by SCMailSetAddress (15.2-6)
  using  the Unix program mail. The optional parameter starttime specifies the
  starting  time  (as  the  integer  Unix timestamp) a calculation was started
  (then  the  duration  of  the  calculation  is  included  in the email), the
  optional  boolean parameter forcesend can be used to force the sending of an
  email,  even  if  this  violates  the  minimal  email  sending interval, see
  SCMailSetMinInterval (15.2-8).
  
    Example  
     gap> SCMailSetAddress("johndoe@somehost"); #enables mail notification
     true
     gap> SCMailIsEnabled();
     true
     gap> SCMailSend("Hello, this is simpcomp.");
     true
     
  
  
  15.2-5 SCMailSendPending
  
  SCMailSendPending(  )  function
  Returns:  true upon success, fail otherwise.
  
  Tries  to  send  a  pending email of the simpcomp email notification system.
  Returns true on success or if there was no mail pending.
  
    Example  
     gap> SCMailSendPending();
     true
     
  
  
  15.2-6 SCMailSetAddress
  
  SCMailSetAddress( address )  function
  Returns:  true upon success, fail otherwise.
  
  Sets the email address that should be used to send notification messages and
  enables   the   mail   notification   system   by  calling  SCMailSetEnabled
  (15.2-7)(true).
  
    Example  
     gap> SCMailSetAddress("johndoe@somehost");
     true
     
  
  
  15.2-7 SCMailSetEnabled
  
  SCMailSetEnabled( flag )  function
  Returns:  true upon success, fail otherwise.
  
  Enables  or disables the mail notification system of simpcomp. By default it
  is  disabled.  Returns  fail  if  no  email  message was previously set with
  SCMailSetAddress (15.2-6).
  
    Example  
     gap> SCMailSetAddress("johndoe@somehost"); #enables mail notification
     true
     gap> SCMailSetEnabled(false);
     true
     
  
  
  15.2-8 SCMailSetMinInterval
  
  SCMailSetMinInterval( interval )  function
  Returns:  true upon success, fail otherwise.
  
  Sets  the minimal time interval in seconds that mail messages can be sent by
  simpcomp.  This  prevents  a  flooding  of  the specified email address with
  messages sent by simpcomp. Default is 3600, i.e. one hour.
  
    Example  
     gap> SCMailSetMinInterval(7200);
     true
     
  
  
  
  15.3 Testing the functionality of simpcomp
  
  simpcomp  makes  use of the GAP internal testing mechanisms and provides the
  user with a function to test the functionality of the package.
  
  15.3-1 SCRunTest
  
  SCRunTest(  )  function
  Returns:  true upon success, fail otherwise.
  
  Test    whether    the   package   simpcomp   is   functional   by   calling
  Test("GAPROOT/pkg/simpcomp/tst/simpcomp.tst",rec(compareFunction          :=
  "uptowhitespace"));.  The  returned value of GAP4stones is a measure of your
  system performance and differs from system to system.
  
    Example  
     gap> SCRunTest();
     simpcomp package test
     GAP4stones: 69463
     true
     
  
  
  On  a  modern computer, the function SCRunTest should take about a minute to
  complete   when  the  packages  GRAPE  [Soi12]  and  homology  [DHSW11]  are
  available.  If  these  packages  are missing, the testing will take slightly
  longer.