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

12.1 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:

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

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

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

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

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




generated by GAPDoc2HTML