Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 Bib Ind
 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 

18 simpcomp internals
 18.1 The GAP object type SCPropertyObject
 18.2 Example of a common attribute
 18.3 Writing a method for an attribute

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:

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:

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);
 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 Bib Ind

generated by GAPDoc2HTML