Goto Chapter: | Top | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | Bib | Ind

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

Top of Book | Previous Chapter | Next Chapter

Goto Chapter: | Top | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | Bib | Ind

generated by GAPDoc2HTML