SCPropertyObject
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.
SCPropertyObjectIn 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.
‣ SCProperties( po ) | ( method ) |
Returns: a record upon success.
Returns the record of all stored properties of the SCPropertyObject po.
‣ SCPropertiesFlush( po ) | ( method ) |
Returns: true upon success.
Drops all properties and temporary properties of the SCPropertyObject po.
‣ 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).
‣ 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).
‣ 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.
‣ 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).
‣ 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)
‣ 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.
‣ 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.
‣ 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.
‣ 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.
‣ 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)
‣ 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.
‣ 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.
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:
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).
First note that the validity of the arguments is checked by GAP. For example, the first method only accepts an argument of type SCSimplicialComplex.
If the property was already computed, the GAP4 type system automatically returns the cached property avoiding unnecessary double calculations.
If the property is not already known. it is computed and returned (and automatically cached by the GAP4 type system).
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);
generated by GAPDoc2HTML