chap18.txt

  
  18 simpcomp internals
  
  The  package  simpcomp works with geometric objects for which the GAP object
  types  SCSimplicialComplex  and  SCNormalSurface  are defined and calculates
  properties  of  these  objects via so called property handlers. This chapter
  describes how to extend simpcomp by writing own property handlers.
  
  If  you  extended simpcomp and want to share your extension with other users
  please  send  your  extension  to  one  of  the authors and we will consider
  including it (of course with giving credit) in a future release of simpcomp.
  
  
  18.1 The GAP object type SCPropertyObject
  
  In the following, we present a number of functions to manage a GAP object of
  type   SCPropertyObject.   Since  most  properties  of  SCPolyhedralComplex,
  SCSimplicialComplex  and SCNormalSurface are managed by the GAP4 type system
  (cf.  [BL98]),  the  functions described below are mainly used by the object
  type SCLibRepository and to store temporary properties.
  
  18.1-1 SCProperties
  
  SCProperties( po )  method
  Returns:  a record upon success.
  
  Returns the record of all stored properties of the SCPropertyObject po.
  
  18.1-2 SCPropertiesFlush
  
  SCPropertiesFlush( po )  method
  Returns:  true upon success.
  
  Drops all properties and temporary properties of the SCPropertyObject po.
  
  18.1-3 SCPropertiesManaged
  
  SCPropertiesManaged( po )  method
  Returns:  a list of managed properties upon success, fail otherwise.
  
  Returns  a  list of all properties that are managed for the SCPropertyObject
  po via property handler functions. See SCPropertyHandlersSet (18.1-9).
  
  18.1-4 SCPropertiesNames
  
  SCPropertiesNames( po )  method
  Returns:  a list upon success.
  
  Returns   a  list  of  all  the  names  of  the  stored  properties  of  the
  SCPropertyObject  po.  These can be accessed via SCPropertySet (18.1-10) and
  SCPropertyDrop (18.1-8).
  
  18.1-5 SCPropertiesTmp
  
  SCPropertiesTmp( po )  method
  Returns:  a record upon success.
  
  Returns  the record of all stored temporary properties (these are mutable in
  contrast  to  regular  properties  and  not  serialized  when  the object is
  serialized to XML) of the SCPropertyObject po.
  
  18.1-6 SCPropertiesTmpNames
  
  SCPropertiesTmpNames( po )  method
  Returns:  a list upon success.
  
  Returns  a  list  of all the names of the stored temporary properties of the
  SCPropertyObject  po.  These  can be accessed via SCPropertyTmpSet (18.1-14)
  and SCPropertyTmpDrop (18.1-13).
  
  18.1-7 SCPropertyByName
  
  SCPropertyByName( po, name )  method
  Returns:  any value upon success, fail otherwise.
  
  Returns  the value of the property with name name of the SCPropertyObject po
  if  this  property  is  known  for po and fail otherwise. The names of known
  properties can be accessed via the function SCPropertiesNames (18.1-4)
  
  18.1-8 SCPropertyDrop
  
  SCPropertyDrop( po, name )  method
  Returns:  true upopn success, fail otherwise
  
  Drops  the  property with name name of the SCPropertyObject po. Returns true
  if  the  property  is  successfully dropped and fail if a property with that
  name did not exist.
  
  18.1-9 SCPropertyHandlersSet
  
  SCPropertyHandlersSet( po, handlers )  method
  Returns:  true
  
  Sets  the  property  handling  functions  for  a  SCPropertyObject po to the
  functions  described  in  the  record  handlers.  The record handlers has to
  contain  entries of the following structure: [Property Name]:=[Function name
  computing  and  returning the property]. For SCSimplicialComplex for example
  simpcomp   defines   (among   many   others):  F:=SCFVector.  See  the  file
  lib/prophandler.gd.
  
  18.1-10 SCPropertySet
  
  SCPropertySet( po, name, data )  method
  Returns:  true upon success.
  
  Sets  the value of the property with name name of the SCPropertyObject po to
  data.  Note  that  the  argument becomes immutable. If this behaviour is not
  desired, use SCPropertySetMutable (18.1-11) instead.
  
  18.1-11 SCPropertySetMutable
  
  SCPropertySetMutable( po, name, data )  method
  Returns:  true upon success.
  
  Sets  the value of the property with name name of the SCPropertyObject po to
  data. Note that the argument does not become immutable. If this behaviour is
  not desired, use SCPropertySet (18.1-10) instead.
  
  18.1-12 SCPropertyTmpByName
  
  SCPropertyTmpByName( po, name )  method
  Returns:  any value upon success, fail otherwise.
  
  Returns  the  value  of  the  temporary  property  with the name name of the
  SCPropertyObject  po  if  this  temporary  property is known for po and fail
  otherwise.  The  names of known temporary properties can be accessed via the
  function SCPropertiesTmpNames (18.1-6)
  
  18.1-13 SCPropertyTmpDrop
  
  SCPropertyTmpDrop( po, name )  method
  Returns:  true upon success, fail otherwise
  
  Drops  the  temporary  property  with  name name of the SCPropertyObject po.
  Returns true if the property is successfully dropped and fail if a temporary
  property with that name did not exist.
  
  18.1-14 SCPropertyTmpSet
  
  SCPropertyTmpSet( po, name, data )  method
  Returns:  true upon success.
  
  Sets   the   value   of  the  temporary  property  with  name  name  of  the
  SCPropertyObject  po  to  data.  Note  that  the  argument  does  not become
  immutable. This is the standard behaviour for temporary properties.
  
  
  18.2 Example of a common attribute
  
  In   this   section   we   will   have   a  look  at  the  property  handler
  SCEulerCharacteristic  (7.3-3)  in  order  to  explain the inner workings of
  property  handlers. This is the code of the property handler for calculating
  the Euler characteristic of a complex in simpcomp:
  
    Example  
    DeclareAttribute("SCEulerCharacteristic",SCIsPolyhedralComplex);
    
    InstallMethod(SCEulerCharacteristic,
    "for SCSimplicialComplex",
    [SCIsSimplicialComplex],
    function(complex)
    
    	local  f, chi, i;
    
    	f:=SCFVector(complex);
    	if f=fail then
    		return fail;
    	fi;
    	chi:=0;
    
    	for i in [1..Size(f)] do
    			chi:=chi + ((-1)^(i+1))*f[i];
    	od;
    
    	return chi;
    end);
    
    InstallMethod(SCEulerCharacteristic,
    "for SCNormalSurface",
    [SCIsNormalSurface],
    function(sl)
    
     	local facets, f, chi;
    
      	
     	f:=SCFVector(sl);
     	if(f=fail) then
     		return fail;
     	fi;
    	
    	if Length(f) = 1 then
    	 		return f[1];
    	elif Length(f) =3 then
     	 		return f[1]-f[2]+f[3];
     	elif Length(f) =4 then
     	 		return f[1]-f[2]+f[3]+f[4];
     	else
     		Info(InfoSimpcomp,1,"SCEulerCharacteristic: illegal f-vector found: ",f,". ");
     		return fail;
     	fi;
    
    end);
    
  
  
  When  looking at the code one already sees the structure that such a handler
  needs to have:
  
  1   Each  property  handler (a GAP operation) needs to be defined. This is
        done by the first line of code. Once an operation is defined, multiple
        methods  can by implemented for various types of GAP objects (here two
        methods  are  implemented for the GAP object types SCSimplicialComplex
        and SCNormalSurface).
  
  2   First  note  that the validity of the arguments is checked by GAP. For
        example,   the   first   method  only  accepts  an  argument  of  type
        SCSimplicialComplex.
  
  3   If   the   property   was  already  computed,  the  GAP4  type  system
        automatically  returns the cached property avoiding unnecessary double
        calculations.
  
  4   If the property is not already known. it is computed and returned (and
        automatically cached by the GAP4 type system).
  
  
  18.3 Writing a method for an attribute
  
  This section provides the skeleton of a method that can be used when writing
  own methods:
  
    Example  
    DeclareAttribute("SCMyPropertyHandler",SCPolyhedralComplex);
    
    InstallMethod(SCMyPropertyHandler,
    "for SCSimplicialComplex[ and further arguments]",
    [SCIsSimplicialComplex[, further arguments]],
    function(complex[, further arguments])
    
    	local myprop, ...;
    
    	# compute the property
     [ do property computation here]
    
    	return myprop;
    end);