simpcomp
internals

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`.

Example of a common property handler

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.
Writing a property handler

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);