GAP (simpcomp) - Chapter 17: simpcomp internals

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

17 simpcomp internals
17.1 The GAP object type `SCPropertyObject`
17.1-1 SCProperties
17.1-2 SCPropertiesFlush
17.1-3 SCPropertiesManaged
17.1-4 SCPropertiesNames
17.1-5 SCPropertiesTmp
17.1-6 SCPropertiesTmpNames
17.1-7 SCPropertyByName
17.1-8 SCPropertyDrop
17.1-9 SCPropertyHandlersSet
17.1-10 SCPropertySet
17.1-11 SCPropertySetMutable
17.1-12 SCPropertyTmpByName
17.1-13 SCPropertyTmpDrop
17.1-14 SCPropertyTmpSet
17.2 Example of a common attribute
17.3 Writing a method for an attribute

### 17 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.

#### 17.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.

##### 17.1-1 SCProperties

`‣ SCProperties`( po ) | ( method )

Returns: a record upon success.

Returns the record of all stored properties of the `SCPropertyObject` po.

##### 17.1-2 SCPropertiesFlush

`‣ SCPropertiesFlush`( po ) | ( method )

Returns: `true` upon success.

Drops all properties and temporary properties of the `SCPropertyObject` po.

##### 17.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` (17.1-9).

##### 17.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` (17.1-10) and `SCPropertyDrop` (17.1-8).

##### 17.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.

##### 17.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` (17.1-14) and `SCPropertyTmpDrop` (17.1-13).

##### 17.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` (17.1-4)

##### 17.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.

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

##### 17.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` (17.1-11) instead.

##### 17.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` (17.1-10) instead.

##### 17.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` (17.1-6)

##### 17.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.

##### 17.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.

#### 17.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).

#### 17.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 Bib Ind

generated by GAPDoc2HTML