The package simpcomp works with simplicial complexes for which a GAP object type SCSimplicialComplex
is defined and calculates properties of these objects via so called property handlers. This chapter describes how to extend simpcomp by writing own property handlers.
By writing own property handlers, simpcomp can be extended in its functionality. 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.
In this section we will have a look at the property handler SCFVector
in oder to explain the inner workings of property handlers. This is the code of the property handler for calculating the f-vector of a complex in simpcomp:
InstallGlobalFunction(SCFVector, function(complex) local f, faces; if(not SCIsSimplicialComplex(complex)) then SCError()("SCFVector: first argument must be of type SCSimplicialComplex.\n"); return fail; fi; f:=SCPropertyByName(complex,"F"); if f<>fail and not SCIntFunc.ForceRecalcEnabled(complex) and IsList(f) and ForAll(f,x->IsInt(x) and x>=0) then return f; else SCPropertyDrop(complex,"F"); faces:=SCFaceLatticeEx(complex); if faces=fail then return fail; fi; f:=List(faces,x->Size(x)); SCPropertySet(complex,"F",f); return f; fi; end); |
When looking at the code one already see the structure that such a handler needs to have:
The arguments are checked for validity -- in case of invalid arguments an error is signaled with SCError()("Error message")
. SCError
then displays the error message and optionally enters a break loop.
It is checked whether the property was computed already with the function SCPropertyByName
-- it takes a complex (as SCPropertyObject
) and a property name (as String
) as arguments and returns the property or fail
if that property does not exist.
If SCPropertyByName
did not return fail
, SCIntFunc.ForceRecalcEnabled(complex)
did return false and the cached property passes a validity check the cached property is returned.
Otherwise the property is first dropped via the function SCPropertyDrop
-- it takes a complex (as SCPropertyObject
) and a property name (as String
) as arguments -- then recomputed and finally written back to the complex via the function SCPropertySet
(that takes a complex, a property name and a property as arguments) and returned.
This section provides the skeleton of a property handler that can be used when writing own property handlers:
DeclareGlobalFunction("SCMyPropertyHandler"); InstallGlobalFunction(SCMyPropertyHandler, function(complex[, further arguments]) local myprop,....; # test arguments if(not SCIsSimplicialComplex(complex)) then SCError()("SCMyPropertyHandler: first argument must be of type SCSimplicialComplex.\n"); return fail; fi; # check if the property that you want to compute is cached myprop:=SCPropertyByName(complex,"MyProperty"); if myprop<>fail and not SCIntFunc.ForceRecalcEnabled(complex) and [check for validity of myprop here] then #return the cached property return myprop; else # first drop the property SCPropertyDrop(complex,"MyProperty"); # now (re)compute the property [ do property computation here] # set the newly created property and return it SCPropertySet(complex,"MyProperty",myprop); return myprop; fi; end); |
generated by GAPDoc2HTML