complex.gd

################################################################################
##
##  simpcomp / complex.gd
##
##  ⪆ object type for simplicial complex   
##
##  $Id$
##
################################################################################
## GAPDoc include
## <#GAPDoc Label="objecttypes">
## In order to meet the particular requirements of piecewise linear geometric 
## objects and their invariants, <Package>simpcomp</Package> defines a number 
## of new &GAP; object types.<P/>
##
## All new object types are derived from the object type 
## <C>SCPropertyObject</C> which is a subtype of <C>Record</C>. It is a &GAP; 
## object consisting of permanent and temporary attributes. While 
## <Package>simpcomp</Package> makes use of &GAP;'s internal attribute caching 
## mechanism for permanent attributes (see below), this is not the case for 
## temporary ones.<P/>
##
## The temporary properties of a <C>SCPropertyObject</C> can be accessed 
## directly with the functions <C>SCPropertyTmpByName</C> and changed with  
## <C>SCPropertyTmpSet</C>. But this direct access to property objects is 
## discouraged when working with <Package>simpcomp</Package>, as the internal 
## consistency of the objects cannot be guaranteed when the properties of the 
## objects are modified in this way.<P/>
##
## Important note: The temporary properties of <C>SCPropertyObject</C> are not 
## used to hold properties (in the &GAP; sense) of simplicial complexes or 
## other geometric objects. This is done by the GAP4 type system 
## <Cite Key="Breuer98GAP4TypeSystem"/>. Instead, the properties handled by 
## <Package>simpcomp</Package>'s own caching mechanism are used to store 
## changing information, e.g. the complex library (see Section 
## <Ref Chap="chap:libio" />) of the package or any other data which possibly 
## is subject to changes (and thus not suited to be stored by the &GAP; type 
## system).<P/> 
##
## To realize its complex library (see Section <Ref Chap="chap:libio" />), 
## <Package>simpcomp</Package> defines a &GAP; object type 
## <C>SCLibRepository</C> which provides the possibility to store, load, etc. 
## any defined geometric object to and from the build-in complex library as 
## well as customized user libraries. In addition, a searching mechanism is 
## provided.<P/>
##
## Geometric objects are represented by the &GAP; object type 
## <C>SCPolyhedralComplex</C>, which as well is a subtype of 
## <C>SCPropertyObject</C>. <C>SCPolyhedralComplex</C> is designed to 
## represent any kind of piecewise linear geometric object given by a certain 
## cell decomposition. Here, as already mentioned, the GAP4 type system
## <Cite Key="Breuer98GAP4TypeSystem"/> is used to cache properties of the 
## object. In this way, a property is not calculated multiple times in case 
## the object is not altered  (see <Ref Func="SCPropertiesDropped" /> for a 
## way of dropping previously calculated properties).<P/>
##
## As of Version 1.4, <Package>simpcomp</Package> makes use of two different 
## subtypes of <C>SCPolyhedralComplex</C>: <C>SCSimplicialComplex</C> to 
## handle simplicial complexes and <C>SCNormalSurface</C> to deal with 
## discrete normal surfaces (slicings of dimension 2). Whenever possible, 
## only one method per operations is implemented to deal with all subtypes 
## of <C>SCPolyhedralComplex</C>, these functions are described in Chapter 
## <Ref Chap="chap:polyhedralcomplex"/>. For all other operations, the 
## different methods for <C>SCSimplicialComplex</C> and 
## <C>SCNormalSurface</C> are documented separately.
##
## <Section Label="sec:AcessSC"> 
## <Heading>Accessing properties of a <C>SCPolyhedralComplex</C> 
## object</Heading>
##
## As described above the object type <C>SCPolyhedralComplex</C> 
## (and thus also the &GAP; object types <C>SCSimplicialComplex</C> 
## and <C>SCNormalSurface</C>) has properties that are handled by the 
## GAP4 type system. Hence, GAP takes care of the internal consistency 
## of objects of type <C>SCSimplicialComplex</C>.<P/>
##
## There are two ways of accessing properties of a <C>SCPolyhedralComplex</C> 
## object. The first is to call a property handler function of the property 
## one wishes to calculate. The first argument of such a property handler 
## function is always the simplicial complex for which the property should 
## be calculated, in some cases followed by further arguments of the 
## property handler function. An example would be:
##
##<Example>
## gap&gt; c:=SCBdSimplex(3);; # create a SCSimplicialComplex object
## gap&gt; SCFVector(c);
## [ 4, 6, 4 ]
## gap&gt; SCSkel(c,0);
## [ [ 1 ], [ 2 ], [ 3 ], [ 4 ] ]
##</Example>
##
## Here the functions <C>SCFVector</C> and <C>SCSkel</C> are the property 
## handler functions, see Chapter <Ref Chap="chap:prophandler" /> for a 
## list of all property handlers of a <C>SCPolyhedralComplex</C>, 
## <C>SCSimplicialComplex</C> or <C>SCNormalSurface</C> object. 
##
## Apart from this (standard) method of calling the property handlers 
## directly with a <C>SCPolyhedralComplex</C> object, 
## <Package>simpcomp</Package> provides the user with another more object 
## oriented method which calls property handlers of a 
## <C>SCPolyhedralComplex</C> object indirectly and more conveniently:
##
##<Example>
## gap&gt; c:=SCBdSimplex(3);; # create a SCSimplicialComplex object
## gap&gt; c.F;
## [ 4, 6, 4 ]
## gap&gt; c.Skel(0);
## [ [ 1 ], [ 2 ], [ 3 ], [ 4 ] ]
##</Example>
##
## Note that the code in this example calculates the same properties as in 
## the first example above, but the properties of a 
## <C>SCPolyhedralComplex</C> object are accessed via the <C>.</C> 
## operator (the record access operator).<P/>
##
## For each property handler of a <C>SCPolyhedralComplex</C> object the 
## object oriented form of this property handler equals the name of the 
## corresponding operation. However, in most cases abbreviations are available: 
## Usually the prefix ``<C>SC</C>'' can be dropped, in other cases even 
## shorter names are available. See Chapter <Ref Chap="chap:prophandler"/> 
## for a complete list of all abbreviations available. 
##
## </Section>
##	
##<#/GAPDoc>
## <#GAPDoc Label="polyhedralcomplex">
##
## In the following all operations for the &GAP; object type 
## <C>SCPolyhedralComplex</C> are listed. I. e. for the following operations 
## only one method is implemented to deal with all geometric objects derived 
## from this object type. 
##
## <Section Label="sec:PCglprops"> 
## <Heading>Computing properties of objects of type 
## <C>SCPolyhedralComplex</C></Heading>
##
##The following functions compute basic properties of objects of type 
## <C>SCPolyhedralComplex</C> (and thus also of objects of type 
## <C>SCSimplicialComplex</C> and <C>SCNormalSurface</C>). None of these 
## functions alter the complex. All properties are returned as immutable 
## objects (this ensures data consistency of the cached properties of a 
## simplicial complex). Use <C>ShallowCopy</C> or the internal 
## <Package>simpcomp</Package> function <C>SCIntFunc.DeepCopy</C> to get a 
## mutable copy.<P/>
## Note: every object is internally stored with the standard vertex labeling 
## from <M>1</M> to <M>n</M> and a maptable to restore the original vertex 
## labeling. Thus, we have to relabel some of the complex properties 
## (facets, etc...) whenever we want to return them to the user. As a 
## consequence, some of the functions exist twice, one of them with the 
## appendix "Ex". These functions return the standard labeling whereas the 
## other ones relabel the result to the original labeling.
##
## <#Include Label="SCFacets"/>
## <#Include Label="SCFacetsEx"/>
## <#Include Label="SCVertices"/>
## <#Include Label="SCVerticesEx"/>
##
## </Section><Section> 
## <Heading>Vertex labelings and label operations</Heading>
##
## This section focuses on functions operating on the labels of a complex 
## such as the name or the vertex labeling.<P/>
## Internally, <Package>simpcomp</Package> uses the standard labeling 
## <M>[1, \ldots , n]</M>. It is recommended to use simple vertex labels 
## like integers and, whenever possible, the standard labeling, see also 
## <Ref Func="SCRelabelStandard" />.
## 
## <#Include Label="SCLabelMax"/>
## <#Include Label="SCLabelMin"/>
## <#Include Label="SCLabels"/>
## <#Include Label="SCName"/>
## <#Include Label="SCReference"/>
## <#Include Label="SCRelabel"/>
## <#Include Label="SCRelabelStandard"/>
## <#Include Label="SCRelabelTransposition"/>
## <#Include Label="SCRename"/>
## <#Include Label="SCSetReference"/>
## <#Include Label="SCUnlabelFace"/>
##
## </Section><Section> 
## <Heading>Operations on objects of type <C>SCPolyhedralComplex</C></Heading>
##
##  The following functions perform operations on objects of type 
## <C>SCPolyhedralComplex</C> and all of its subtypes. Most of them return 
## simplicial complexes. Thus, this section is closely related to the Sections 
## <Ref Chap="sec:generateFromOld"/> (for objects of type 
## <C>SCSimplicialComplex</C>), ''Generate new complexes from old''. However, 
## the data generated here is rather seen as an intrinsic attribute of the 
## original complex and not as an independent complex.
##
## <#Include Label="SCAntiStar"/>
## <#Include Label="SCLink"/>
## <#Include Label="SCLinks"/>
## <#Include Label="SCStar"/>
## <#Include Label="SCStars"/>
##
## </Section>
##<#/GAPDoc>
## <#GAPDoc Label="complex">
##
## Currently, the &GAP; package <Package>simpcomp</Package> supports data 
## structures for two different kinds of geometric objects, namely simplicial 
## complexes (<C>SCSimplicialComplex</C>) and discrete normal surfaces 
## (<C>SCNormalSurface</C>) which are both subtypes of the &GAP; object 
## type <C>SCPolyhedralComplex</C>
## 
## <Section Label="sec:SCSimplComplObj">
## <Heading>The object type <C>SCSimplicialComplex</C></Heading>
##
## A major part of <Package>simpcomp</Package> deals with the object type 
## <C>SCSimplicialComplex</C>. For a complete list of properties that 
## <C>SCSimplicialComplex</C> handles, see Chapter <Ref Chap="chap:scfunc" />. 
## For a few fundamental methods and functions (such as checking the object
## class, copying objects of this type, etc.) for <C>SCSimplicialComplex</C> 
## see below. 
##
## <#Include Label="SCIsSimplicialComplex"/>
## <#Include Label="SCCopy"/>
## <#Include Label="SCShallowCopy"/>
## <#Include Label="SCPropertiesDropped"/>
##
## </Section>
## <Section>
## <Heading>Overloaded operators of <C>SCSimplicialComplex</C></Heading>
##
## <Package>simpcomp</Package> overloads some standard operations for the 
## object type <C>SCSimplicialComplex</C> if this definition is intuitive and 
## mathematically sound. See a list of overloaded operators below. 
##	
## <#Include Label="SCOpPlusSCInt"/>
## <#Include Label="SCOpMinusSCInt"/>
## <#Include Label="SCOpModSCInt"/>
## <#Include Label="SCOpPowSCInt"/>
## <#Include Label="SCOpPlusSCSC"/>
## <#Include Label="SCOpMinusSCSC"/>
## <#Include Label="SCOpMultSCSC"/>
## <#Include Label="SCOpEqSCSC"/>
##	
## </Section> 
##
## <Section Label="sec:SubtypeOfSet"> 
## <Heading><C>SCSimplicialComplex</C> as a subtype of <C>Set</C></Heading>
##	
## Apart from being a subtype of <C>SCPropertyObject</C>, an object of type 
## <C>SCSimplicialComplex</C> also behaves like a &GAP; <C>Set</C> type. The 
## elements of the set are given by the facets of the simplical complex, 
## grouped by their dimensionality, i.e. if <C>complex</C> is an object of 
## type <C>SCSimplicialComplex</C>, <C>c[1]</C> refers to the 0-faces of 
## <C>complex</C>, <C>c[2]</C> to the 1-faces, etc.
##
## <#Include Label="SCOpUnionSCSC"/>
## <#Include Label="SCOpDiffSCSC"/>
## <#Include Label="SCOpIsecSCSC"/>
## <#Include Label="SCSize"/>
## <#Include Label="SCLength"/>
## <#Include Label="SCAccess"/>
## <#Include Label="SCIterator"/>
##	
## </Section> 
##		
##<#/GAPDoc>
################################################################################