GAP (simpcomp) - Chapter 5: The GAP object types SCSimplicialComplex and SCNormalSurface

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]

[MathJax off]

5 The GAP object types `SCSimplicialComplex` and `SCNormalSurface`
5.1 The object type `SCSimplicialComplex`
5.1-1 SCIsSimplicialComplex
5.1-2 SCDetails
5.1-3 SCCopy
5.1-4 ShallowCopy (SCSimplicialComplex)
5.1-5 SCPropertiesDropped
5.2 Overloaded operators of `SCSimplicialComplex`
5.2-1 Operation + (SCSimplicialComplex, Integer)
5.2-2 Operation - (SCSimplicialComplex, Integer)
5.2-3 Operation mod (SCSimplicialComplex, Integer)
5.2-4 Operation ^ (SCSimplicialComplex, Integer)
5.2-5 Operation + (SCSimplicialComplex, SCSimplicialComplex)
5.2-6 Operation - (SCSimplicialComplex, SCSimplicialComplex)
5.2-7 Operation * (SCSimplicialComplex, SCSimplicialComplex)
5.2-8 Operation = (SCSimplicialComplex, SCSimplicialComplex)
5.3 `SCSimplicialComplex` as a subtype of `Set`
5.3-1 Operation Union (SCSimplicialComplex, SCSimplicialComplex)
5.3-2 Operation Difference (SCSimplicialComplex, SCSimplicialComplex)
5.3-3 Operation Intersection (SCSimplicialComplex, SCSimplicialComplex)
5.3-4 Size (SCSimplicialComplex)
5.3-5 Length (SCSimplicialComplex)
5.3-6 Operation [] (SCSimplicialComplex)
5.3-7 Iterator (SCSimplicialComplex)
5.4 The object type `SCNormalSurface`
5.5 Overloaded operators of `SCNormalSurface`
5.5-1 Operation + (SCNormalSurface, Integer)
5.5-2 Operation - (SCNormalSurface, Integer)
5.5-3 Operation mod (SCNormalSurface, Integer)
5.6 `SCNormalSurface` as a subtype of `Set`
5.6-1 Operation Union (SCNormalSurface, SCNormalSurface)

### 5 The GAP object types `SCSimplicialComplex` and `SCNormalSurface`

Currently, the GAP package simpcomp supports data structures for two different kinds of geometric objects, namely simplicial complexes (`SCSimplicialComplex`) and discrete normal surfaces (`SCNormalSurface`) which are both subtypes of the GAP object type `SCPolyhedralComplex`

#### 5.1 The object type `SCSimplicialComplex`

A major part of simpcomp deals with the object type `SCSimplicialComplex`. For a complete list of properties that `SCSimplicialComplex` handles, see Chapter 6. For a few fundamental methods and functions (such as checking the object class, copying objects of this type, etc.) for `SCSimplicialComplex` see below.

##### 5.1-1 SCIsSimplicialComplex

`‣ SCIsSimplicialComplex`( object ) | ( filter )

Returns: `true` or `false` upon success, `fail` otherwise.

Checks if object is of type `SCSimplicialComplex`. The object type `SCSimplicialComplex` is derived from the object type `SCPropertyObject`.

     gap> c:=SCEmpty();;
     gap> SCIsSimplicialComplex(c);
     true

##### 5.1-2 SCDetails

`‣ SCDetails`( complex ) | ( function )

Returns: a string of type `IsString` upon success, `fail` otherwise.

The function returns a list of known properties of complex an lists some of these properties explicitly.

     gap> c:=SC([[1,2,3],[1,2,4],[1,3,4],[2,3,4]]);
     <SimplicialComplex: unnamed complex 1 | dim = 2 | n = 4>
     gap> Print(SCDetails(c));
     [SimplicialComplex

      Properties known: Dim, FacetsEx, Name, Vertices.
      Name="unnamed complex 1"
      Dim=2

     /SimplicialComplex]
     gap> c.F;
     [ 4, 6, 4 ]
     gap> c.Homology;
     [ [ 0, [  ] ], [ 0, [  ] ], [ 1, [  ] ] ]
     gap> Print(SCDetails(c));
     [SimplicialComplex

      Properties known: Dim, FacetsEx, Homology, Name, Vertices.
      Name="unnamed complex 1"
      Dim=2
      Homology=[ [ 0, [ ] ], [ 0, [ ] ], [ 1, [ ] ] ]

     /SimplicialComplex]

##### 5.1-3 SCCopy

`‣ SCCopy`( complex ) | ( method )

Returns: a copy of complex upon success, `fail` otherwise.

Makes a ``deep copy'' of complex -- this is a copy such that all properties of the copy can be altered without changing the original complex.

     gap> c:=SCBdSimplex(4);;
     gap> d:=SCCopy(c)-1;;
     gap> c.Facets=d.Facets;
     false

     gap> c:=SCBdSimplex(4);;
     gap> d:=SCCopy(c);;
     gap> IsIdenticalObj(c,d);
     false

##### 5.1-4 ShallowCopy (SCSimplicialComplex)

`‣ ShallowCopy (SCSimplicialComplex)`( complex ) | ( method )

Returns: a copy of complex upon success, `fail` otherwise.

Makes a copy of complex. This is actually a ``deep copy'' such that all properties of the copy can be altered without changing the original complex. Internally calls `SCCopy` (5.1-3).

     gap> c:=SCBdCrossPolytope(7);;
     gap> d:=ShallowCopy(c)+10;;
     gap> c.Facets=d.Facets;
     false

##### 5.1-5 SCPropertiesDropped

`‣ SCPropertiesDropped`( complex ) | ( function )

Returns: a object of type `SCSimplicialComplex` upon success, `fail` otherwise.

An object of the type `SCSimplicialComplex` caches its previously calculated properties such that each property only has to be calculated once. This function returns a copy of complex with all properties (apart from Facets, Dim and Name) dropped, clearing all previously computed properties. See also `SCPropertyDrop` (18.1-8) and `SCPropertyTmpDrop` (18.1-13).

     gap> c:=SC(SCFacets(SCBdCyclicPolytope(10,12)));
     <SimplicialComplex: unnamed complex 27 | dim = 9 | n = 12>
     gap> c.F; time;
     [ 12, 66, 220, 495, 792, 922, 780, 465, 180, 36 ]
     39
     gap> c.F; time;
     [ 12, 66, 220, 495, 792, 922, 780, 465, 180, 36 ]
     71
     gap> c:=SCPropertiesDropped(c);
     <SimplicialComplex: unnamed complex 27 | dim = 9 | n = 12>
     gap> c.F; time;
     [ 12, 66, 220, 495, 792, 922, 780, 465, 180, 36 ]
     54

#### 5.2 Overloaded operators of `SCSimplicialComplex`

simpcomp overloads some standard operations for the object type `SCSimplicialComplex` if this definition is intuitive and mathematically sound. See a list of overloaded operators below.

##### 5.2-1 Operation + (SCSimplicialComplex, Integer)

`‣ Operation + (SCSimplicialComplex, Integer)`( complex, value ) | ( method )

Returns: the simplicial complex passed as argument upon success, `fail` otherwise.

Positively shifts the vertex labels of complex (provided that all labels satisfy the property `IsAdditiveElement`) by the amount specified in value.

     gap> c:=SCBdSimplex(3)+10;;
     gap> c.Facets;
     [ [ 11, 12, 13 ], [ 11, 12, 14 ], [ 11, 13, 14 ], [ 12, 13, 14 ] ]

##### 5.2-2 Operation - (SCSimplicialComplex, Integer)

`‣ Operation - (SCSimplicialComplex, Integer)`( complex, value ) | ( method )

Returns: the simplicial complex passed as argument upon success, `fail` otherwise.

Negatively shifts the vertex labels of complex (provided that all labels satisfy the property `IsAdditiveElement`) by the amount specified in value.

     gap> c:=SCBdSimplex(3)-1;;
     gap> c.Facets;
     [ [ 0, 1, 2 ], [ 0, 1, 3 ], [ 0, 2, 3 ], [ 1, 2, 3 ] ]

##### 5.2-3 Operation mod (SCSimplicialComplex, Integer)

`‣ Operation mod (SCSimplicialComplex, Integer)`( complex, value ) | ( method )

Returns: the simplicial complex passed as argument upon success, `fail` otherwise.

Takes all vertex labels of complex modulo the value specified in value (provided that all labels satisfy the property `IsAdditiveElement`). Warning: this might result in different vertices being assigned the same label or even in invalid facet lists, so be careful.

     gap> c:=(SCBdSimplex(3)*10) mod 7;;
     gap> c.Facets;
     [ [ 2, 3, 5 ], [ 2, 3, 6 ], [ 2, 5, 6 ], [ 3, 5, 6 ] ]

##### 5.2-4 Operation ^ (SCSimplicialComplex, Integer)

`‣ Operation ^ (SCSimplicialComplex, Integer)`( complex, value ) | ( method )

Returns: simplicial complex of type `SCSimplicialComplex` upon success, `fail` otherwise.

Forms the value-th simplicial cartesian power of complex, i.e. the value-fold cartesian product of copies of complex. The complex passed as argument is not altered. Internally calls `SCCartesianPower` (6.6-1).

     gap> c:=SCBdSimplex(2)^2; #a torus
     <SimplicialComplex: (S^1_3)^2 | dim = 2 | n = 9>

##### 5.2-5 Operation + (SCSimplicialComplex, SCSimplicialComplex)

`‣ Operation + (SCSimplicialComplex, SCSimplicialComplex)`( complex1, complex2 ) | ( method )

Returns: simplicial complex of type `SCSimplicialComplex` upon success, `fail` otherwise.

Forms the connected sum of complex1 and complex2. Uses the lexicographically first facets of both complexes to do the gluing. The complexes passed as arguments are not altered. Internally calls `SCConnectedSum` (6.6-5).

     gap> SCLib.SearchByName("RP^3");;
     gap> c:=SCLib.Load(last[1][1]);;
     gap> SCLib.SearchByName("S^2~S^1"){[1..3]};
     [ [ 12, "S^2~S^1 (VT)" ], [ 26, "S^2~S^1 (VT)" ], [ 27, "S^2~S^1 (VT)" ] ]
     gap> d:=SCLib.Load(last[1][1]);;
     gap> c:=c+d; #form RP^3#(S^2~S^1)
     <SimplicialComplex: RP^3#+-S^2~S^1 (VT) | dim = 3 | n = 16>

##### 5.2-6 Operation - (SCSimplicialComplex, SCSimplicialComplex)

`‣ Operation - (SCSimplicialComplex, SCSimplicialComplex)`( complex1, complex2 ) | ( method )

Returns: simplicial complex of type `SCSimplicialComplex` upon success, `fail` otherwise.

Calls `SCDifference` (6.10-5)(complex1, complex2)

##### 5.2-7 Operation * (SCSimplicialComplex, SCSimplicialComplex)

`‣ Operation * (SCSimplicialComplex, SCSimplicialComplex)`( complex1, complex2 ) | ( method )

Returns: simplicial complex of type `SCSimplicialComplex` upon success, `fail` otherwise.

Forms the simplicial cartesian product of complex1 and complex2. Internally calls `SCCartesianProduct` (6.6-2).

     gap> SCLib.SearchByName("RP^2");
     [ [ 3, "RP^2 (VT)" ], [ 262, "RP^2xS^1" ] ]
     gap> c:=SCLib.Load(last[1][1])*SCBdSimplex(3); #form RP^2 x S^2
     <SimplicialComplex: RP^2 (VT)xS^2_4 | dim = 4 | n = 24>

##### 5.2-8 Operation = (SCSimplicialComplex, SCSimplicialComplex)

`‣ Operation = (SCSimplicialComplex, SCSimplicialComplex)`( complex1, complex2 ) | ( method )

Returns: `true` or `false` upon success, `fail` otherwise.

Calculates whether two simplicial complexes are isomorphic, i.e. are equal up to a relabeling of the vertices.

     gap> c:=SCBdSimplex(3);;
     gap> c=c+10;
     true
     gap> c=SCBdCrossPolytope(4);
     false

#### 5.3 `SCSimplicialComplex` as a subtype of `Set`

Apart from being a subtype of `SCPropertyObject`, an object of type `SCSimplicialComplex` also behaves like a GAP `Set` type. The elements of the set are given by the facets of the simplical complex, grouped by their dimensionality, i.e. if `complex` is an object of type `SCSimplicialComplex`, `c[1]` refers to the 0-faces of `complex`, `c[2]` to the 1-faces, etc.

##### 5.3-1 Operation Union (SCSimplicialComplex, SCSimplicialComplex)

`‣ Operation Union (SCSimplicialComplex, SCSimplicialComplex)`( complex1, complex2 ) | ( method )

Returns: simplicial complex of type `SCSimplicialComplex` upon success, `fail` otherwise.

Computes the union of two simplicial complexes by calling `SCUnion` (7.3-16).

     gap> c:=Union(SCBdSimplex(3),SCBdSimplex(3)+3); #a wedge of two 2-spheres
     <SimplicialComplex: S^2_4 cup S^2_4 | dim = 2 | n = 7>

##### 5.3-2 Operation Difference (SCSimplicialComplex, SCSimplicialComplex)

`‣ Operation Difference (SCSimplicialComplex, SCSimplicialComplex)`( complex1, complex2 ) | ( method )

Returns: simplicial complex of type `SCSimplicialComplex` upon success, `fail` otherwise.

Computes the ``difference'' of two simplicial complexes by calling `SCDifference` (6.10-5).

     gap> c:=SCBdSimplex(3);;
     gap> d:=SC([[1,2,3]]);;
     gap> disc:=Difference(c,d);;
     gap> disc.Facets;
     [ [ 1, 2, 4 ], [ 1, 3, 4 ], [ 2, 3, 4 ] ]
     gap> empty:=Difference(d,c);;
     gap> empty.Dim;
     -1

##### 5.3-3 Operation Intersection (SCSimplicialComplex, SCSimplicialComplex)

`‣ Operation Intersection (SCSimplicialComplex, SCSimplicialComplex)`( complex1, complex2 ) | ( method )

Returns: simplicial complex of type `SCSimplicialComplex` upon success, `fail` otherwise.

Computes the ``intersection'' of two simplicial complexes by calling `SCIntersection` (6.10-8).

     gap> c:=SCBdSimplex(3);;
     gap> d:=SCBdSimplex(3);;
     gap> d:=SCMove(d,[[1,2,3],[]]);;
     gap> d:=d+1;;
     gap> s1.Facets;
     Error, Variable: 's1' must have a value
     not in any function at *stdin*:77

##### 5.3-4 Size (SCSimplicialComplex)

`‣ Size (SCSimplicialComplex)`( complex ) | ( method )

Returns: an integer upon success, `fail` otherwise.

Returns the ``size'' of a simplicial complex. This is \(d+1\), where \(d\) is the dimension of the complex. \(d+1\) is returned instead of \(d\), as all lists in GAP are indexed beginning with 1 -- thus this also holds for all the face lattice related properties of the complex.

     gap> SCLib.SearchByAttribute("F=[12,66,108,54]");;
     gap> c:=SCLib.Load(last[1][1]);;
     gap> for i in [1..Size(c)] do Print(c.F[i],"\n"); od;
     12
     66
     108
     54

##### 5.3-5 Length (SCSimplicialComplex)

`‣ Length (SCSimplicialComplex)`( complex ) | ( method )

Returns: an integer upon success, `fail` otherwise.

Returns the ``size'' of a simplicial complex by calling `Size(`complex`)`.

     gap> SCLib.SearchByAttribute("F=[12,66,108,54]");;
     gap> c:=SCLib.Load(last[1][1]);;
     gap> for i in [1..Length(c)] do Print(c.F[i],"\n"); od;
     12
     66
     108
     54

##### 5.3-6 Operation [] (SCSimplicialComplex)

`‣ Operation [] (SCSimplicialComplex)`( complex, pos ) | ( method )

Returns: a list of faces upon success, `fail` otherwise.

Returns the \((pos-1)\)-dimensional faces of complex as a list. If \(pos \geq d+2\), where \(d\) is the dimension of complex, the empty set is returned. Note that pos must be \(\geq 1\).

     gap> SCLib.SearchByName("K^2");
     [ [ 18, "K^2 (VT)" ], [ 221, "K^2 (VT)" ] ]
     gap> c:=SCLib.Load(last[1][1]);;
     gap> c[2];
     [ [ 1, 2 ], [ 1, 3 ], [ 1, 5 ], [ 1, 7 ], [ 1, 9 ], [ 1, 10 ], [ 2, 3 ],
       [ 2, 4 ], [ 2, 6 ], [ 2, 8 ], [ 2, 10 ], [ 3, 4 ], [ 3, 5 ], [ 3, 7 ],
       [ 3, 9 ], [ 4, 5 ], [ 4, 6 ], [ 4, 8 ], [ 4, 10 ], [ 5, 6 ], [ 5, 7 ],
       [ 5, 9 ], [ 6, 7 ], [ 6, 8 ], [ 6, 10 ], [ 7, 8 ], [ 7, 9 ], [ 8, 9 ],
       [ 8, 10 ], [ 9, 10 ] ]
     gap> c[4];
     [  ]

##### 5.3-7 Iterator (SCSimplicialComplex)

`‣ Iterator (SCSimplicialComplex)`( complex ) | ( method )

Returns: an iterator on the face lattice of complex upon success, `fail` otherwise.

Provides an iterator object for the face lattice of a simplicial complex.

     gap> c:=SCBdCrossPolytope(4);;
     gap> for faces in c do Print(Length(faces),"\n"); od;
     8
     24
     32
     16

#### 5.4 The object type `SCNormalSurface`

The GAP object type `SCNormalSurface` is designed to describe slicings (level sets of discrete Morse functions) of combinatorial \(3\)-manifolds, i. e. discrete normal surfaces. Internally `SCNormalSurface` is a subtype of `SCPolyhedralComplex` and, thus, mostly behaves like a `SCSimplicialComplex` object (see Section 5.1). For a very short introduction to normal surfaces see 2.4, for a more thorough introduction to the field see [Spr11b]. For some fundamental methods and functions for `SCNormalSurface` see below. For more functions related to the `SCNormalSurface` object type see Chapter 7.

#### 5.5 Overloaded operators of `SCNormalSurface`

As with the object type `SCSimplicialComplex`, simpcomp overloads some standard operations for the object type `SCNormalSurface`. See a list of overloaded operators below.

##### 5.5-1 Operation + (SCNormalSurface, Integer)

`‣ Operation + (SCNormalSurface, Integer)`( complex, value ) | ( method )

Returns: the discrete normal surface passed as argument upon success, `fail` otherwise.

Positively shifts the vertex labels of complex (provided that all labels satisfy the property `IsAdditiveElement`) by the amount specified in value.

     gap> sl:=SCNSSlicing(SCBdSimplex(4),[[1],[2..5]]);;
     gap> sl.Facets;
     [ [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ] ], [ [ 1, 2 ], [ 1, 3 ], [ 1, 5 ] ],
       [ [ 1, 2 ], [ 1, 4 ], [ 1, 5 ] ], [ [ 1, 3 ], [ 1, 4 ], [ 1, 5 ] ] ]
     gap> sl:=sl + 2;;
     gap> sl.Facets;
     [ [ [ 3, 4 ], [ 3, 5 ], [ 3, 6 ] ], [ [ 3, 4 ], [ 3, 5 ], [ 3, 7 ] ],
       [ [ 3, 4 ], [ 3, 6 ], [ 3, 7 ] ], [ [ 3, 5 ], [ 3, 6 ], [ 3, 7 ] ] ]

##### 5.5-2 Operation - (SCNormalSurface, Integer)

`‣ Operation - (SCNormalSurface, Integer)`( complex, value ) | ( method )

Returns: the discrete normal surface passed as argument upon success, `fail` otherwise.

Negatively shifts the vertex labels of complex (provided that all labels satisfy the property `IsAdditiveElement`) by the amount specified in value.

     gap> sl:=SCNSSlicing(SCBdSimplex(4),[[1],[2..5]]);;
     gap> sl.Facets;
     [ [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ] ], [ [ 1, 2 ], [ 1, 3 ], [ 1, 5 ] ],
       [ [ 1, 2 ], [ 1, 4 ], [ 1, 5 ] ], [ [ 1, 3 ], [ 1, 4 ], [ 1, 5 ] ] ]
     gap> sl:=sl - 2;;
     gap> sl.Facets;
     [ [ [ -1, 0 ], [ -1, 1 ], [ -1, 2 ] ], [ [ -1, 0 ], [ -1, 1 ], [ -1, 3 ] ],
       [ [ -1, 0 ], [ -1, 2 ], [ -1, 3 ] ], [ [ -1, 1 ], [ -1, 2 ], [ -1, 3 ] ] ]

##### 5.5-3 Operation mod (SCNormalSurface, Integer)

`‣ Operation mod (SCNormalSurface, Integer)`( complex, value ) | ( method )

Returns: the discrete normal surface passed as argument upon success, `fail` otherwise.

Takes all vertex labels of complex modulo the value specified in value (provided that all labels satisfy the property `IsAdditiveElement`). Warning: this might result in different vertices being assigned the same label or even invalid facet lists, so be careful.

     gap> sl:=SCNSSlicing(SCBdSimplex(4),[[1],[2..5]]);;
     gap> sl.Facets;
     [ [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ] ], [ [ 1, 2 ], [ 1, 3 ], [ 1, 5 ] ],
       [ [ 1, 2 ], [ 1, 4 ], [ 1, 5 ] ], [ [ 1, 3 ], [ 1, 4 ], [ 1, 5 ] ] ]
     gap> sl:=sl mod 2;;
     gap> sl.Facets;
     [ [ [ 1, 0 ], [ 1, 0 ], [ 1, 1 ] ], [ [ 1, 0 ], [ 1, 0 ], [ 1, 1 ] ],
       [ [ 1, 0 ], [ 1, 1 ], [ 1, 1 ] ], [ [ 1, 0 ], [ 1, 1 ], [ 1, 1 ] ] ]

#### 5.6 `SCNormalSurface` as a subtype of `Set`

Like objects of type `SCSimplicialComplex`, an object of type `SCNormalSurface` behaves like a GAP `Set` type. The elements of the set are given by the facets of the normal surface, grouped by their dimensionality and type, i.e. if `complex` is an object of type `SCNormalSurface`, `c[1]` refers to the 0-faces of `complex`, `c[2]` to the 1-faces, `c[3]` to the triangles and `c[4]` to the quadrilaterals. See below for some examples and Section 5.3 for details.

##### 5.6-1 Operation Union (SCNormalSurface, SCNormalSurface)

`‣ Operation Union (SCNormalSurface, SCNormalSurface)`( complex1, complex2 ) | ( method )

Returns: discrete normal surface of type `SCNormalSurface` upon success, `fail` otherwise.

Computes the union of two discrete normal surfaces by calling `SCUnion` (7.3-16).

     gap> SCLib.SearchByAttribute("F = [ 10, 35, 50, 25 ]");
     [ [ 19, "S^3 (VT)" ] ]
     gap> c:=SCLib.Load(last[1][1]);;
     gap> sl1:=SCNSSlicing(c,[[1,3,5,7,9],[2,4,6,8,10]]);;
     gap> sl2:=sl1+10;;
     gap> SCTopologicalType(sl1);
     "T^2"
     gap> sl3:=Union(sl1,sl2);;
     gap> SCTopologicalType(sl3);
     "T^2 U T^2"

[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