4 Functions and operations for the GAP object type SCPolyhedralComplex
  
  In  the following all operations for the GAP object type SCPolyhedralComplex
  are  listed.  I.  e.  for  the  following  operations  only  one  method  is
  implemented  to  deal  with  all  geometric objects derived from this object
  type.
  
  
  4.1 Computing properties of objects of type SCPolyhedralComplex
  
  The  following  functions  compute  basic  properties  of  objects  of  type
  SCPolyhedralComplex  (and  thus  also of objects of type SCSimplicialComplex
  and  SCNormalSurface).  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 ShallowCopy or the
  internal simpcomp function SCIntFunc.DeepCopy to get a mutable copy.
  
  Note:  every  object  is internally stored with the standard vertex labeling
  from 1 to n 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.
  
  4.1-1 SCFacets
  
  SCFacets( complex )  method
  Returns:  a facet list upon success, fail otherwise.
  
  Returns the facets of a simplicial complex in the original vertex labeling.
  
    Example  
     gap> c:=SC([[2,3],[3,4],[4,2]]);;
     gap> SCFacets(c);
     [ [ 2, 3 ], [ 2, 4 ], [ 3, 4 ] ]
     
  
  
  4.1-2 SCFacetsEx
  
  SCFacetsEx( complex )  method
  Returns:  a facet list upon success, fail otherwise.
  
  Returns  the  facets  of a simplicial complex as they are stored, i. e. with
  standard vertex labeling from 1 to n.
  
    Example  
     gap> c:=SC([[2,3],[3,4],[4,2]]);;
     gap> SCFacetsEx(c);
     [ [ 1, 2 ], [ 1, 3 ], [ 2, 3 ] ]
     
  
  
  4.1-3 SCVertices
  
  SCVertices( complex )  method
  Returns:  a list of vertex labels of complex upon success, fail otherwise.
  
  Returns the vertex labels of a simplicial complex complex.
  
    Example  
     gap> sphere:=SC([["x",45,[1,1]],["x",45,["b",3]],["x",[1,1],
       ["b",3]],[45,[1,1],["b",3]]]);;
     gap> SCVerticesEx(sphere);
     [ 1 .. 4 ]
     gap> SCVertices(sphere);
     [ 45, [ 1, 1 ], "x", [ "b", 3 ] ]
     
  
  
  4.1-4 SCVerticesEx
  
  SCVerticesEx( complex )  method
  Returns:  [ 1, ... , n ] upon success, fail otherwise.
  
  Returns  [1,  ...  ,  n ], where n is the number of vertices of a simplicial
  complex complex.
  
    Example  
     gap> c:=SC([[1,4,5],[4,9,8],[12,13,14,15,16,17]]);;
     gap> SCVerticesEx(c);
     [ 1 .. 11 ]
     
  
  
  
  4.2 Vertex labelings and label operations
  
  This  section focuses on functions operating on the labels of a complex such
  as the name or the vertex labeling.
  
  Internally,  simpcomp  uses  the  standard  labeling  [1,  ...  ,  n]. It is
  recommended  to  use  simple  vertex  labels  like  integers  and,  whenever
  possible, the standard labeling, see also SCRelabelStandard (4.2-7).
  
  4.2-1 SCLabelMax
  
  SCLabelMax( complex )  method
  Returns:  vertex  label of complex (an integer, a short list, a character, a
            short string) upon success, fail otherwise.
  
  The  maximum  over  all  vertex  labels  is  determined  by the GAP function
  MaximumList.
  
    Example  
     gap> c:=SCBdSimplex(3);;
     gap> SCRelabel(c,[10,100,100000,3500]);;
     gap> SCLabelMax(c);
     100000
     
  
  
    Example  
     gap> c:=SCBdSimplex(3);;
     gap> SCRelabel(c,["a","bbb",5,[1,1]]);;
     gap> SCLabelMax(c);
     "bbb"
     
  
  
  4.2-2 SCLabelMin
  
  SCLabelMin( complex )  method
  Returns:  vertex  label of complex (an integer, a short list, a character, a
            short string) upon success, fail otherwise.
  
  The  minimum  over  all  vertex  labels  is  determined  by the GAP function
  MinimumList.
  
    Example  
     gap> c:=SCBdSimplex(3);;
     gap> SCRelabel(c,[10,100,100000,3500]);;
     gap> SCLabelMin(c);
     10
     
  
  
    Example  
     gap> c:=SCBdSimplex(3);;
     gap> SCRelabel(c,["a","bbb",5,[1,1]]);;
     gap> SCLabelMin(c);
     5
     
  
  
  4.2-3 SCLabels
  
  SCLabels( complex )  method
  Returns:  a  list  of  vertex  labels  of complex (a list of integers, short
            lists,   characters,   short  strings,  ...)  upon  success,  fail
            otherwise.
  
  Returns  the  vertex  labels  of  complex  as  a  list. This is a synonym of
  SCVertices (4.1-3).
  
    Example  
     gap> c:=SCFromFacets(Combinations(["a","b","c","d"],3));;
     gap> SCLabels(c);
     [ "a", "b", "c", "d" ]
     
  
  
  4.2-4 SCName
  
  SCName( complex )  operation
  Returns:  a string upon success, fail otherwise.
  
  Returns the name of a simplicial complex complex.
  
    Example  
     gap> c:=SCBdSimplex(5);;
     gap> SCName(c);
     "S^4_6"
     
  
  
    Example  
     gap> c:=SC([[1,2],[2,3],[3,1]]);;
     gap> SCName(c);
     "unnamed complex 2"
     
  
  
  4.2-5 SCReference
  
  SCReference( complex )  operation
  Returns:  a string upon success, fail otherwise.
  
  Returns a literature reference of a polyhedral complex complex.
  
    Example  
     gap> c:=SCLib.Load(253);;
     gap> SCReference(c);
     "F.H.Lutz: 'The Manifold Page', http://www.math.tu-berlin.de/diskregeom/stella\
     r/"
     gap> c:=SC([[1,2],[2,3],[3,1]]);;
     gap> SCReference(c);
     #I  SCReference: complex lacks reference.
     fail
     
  
  
  4.2-6 SCRelabel
  
  SCRelabel( complex, maptable )  method
  Returns:  true upon success, fail otherwise.
  
  maptable  has  to be a list of length n where n is the number of vertices of
  complex.  The  function maps the i-th entry of maptable to the i-th entry of
  the  current  vertex labels. If complex has the standard vertex labeling [1,
  ... , n] the vertex label i is mapped to maptable[i].
  
  Note  that  the  elements  of  maptable  must admit a total ordering. Hence,
  following Section 4.11 of the GAP manual, they must be members of one of the
  following  families: rationals IsRat, cyclotomics IsCyclotomic, finite field
  elements  IsFFE, permutations IsPerm, booleans IsBool, characters IsChar and
  lists (strings) IsList.
  
  Internally the property ``SCVertices'' of complex is replaced by maptable.
  
    Example  
     gap> list:=SCLib.SearchByAttribute("F[1]=12");; 
     gap> c:=SCLib.Load(list[1][1]);;
     gap> SCVertices(c);
     [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ]
     gap> SCRelabel(c,["a","b","c","d","e","f","g","h","i","j","k","l"]);
     true
     gap> SCLabels(c);
     [ "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l" ]
     
  
  
  4.2-7 SCRelabelStandard
  
  SCRelabelStandard( complex )  method
  Returns:  true upon success, fail otherwise.
  
  Maps  vertex  labels v_1 , ... , v_n of complex to [1 , ... , n]. Internally
  the property "SCVertices" is replaced by [1 , ... , n].
  
    Example  
     gap> list:=SCLib.SearchByAttribute("F[1]=12");; 
     gap> c:=SCLib.Load(list[1][1]);;
     gap> SCRelabel(c,[4..15]);
     true
     gap> SCVertices(c);
     [ 4 .. 15 ]
     gap> SCRelabelStandard(c);
     true
     gap> SCLabels(c);
     [ 1 .. 12 ]
     
  
  
  4.2-8 SCRelabelTransposition
  
  SCRelabelTransposition( complex, pair )  method
  Returns:  true upon success, fail otherwise.
  
  Permutes  vertex  labels of a single pair of vertices. pair has to be a list
  of length 2 and a sublist of the property ``SCVertices''.
  
  The   function  is  equivalent  to  SCRelabel  (4.2-6)  with  maptable  =  [
  SCVertices[1]  ,  ...  ,  SCVertices[j]  ,  ...  ,  SCVertices[i]  ,  dots ,
  SCVertices[n]] if pair = [ SCVertices[j] , SCVertices[i]], j ≤ i, j ≠ i.
  
    Example  
     gap> c:=SCBdSimplex(3);;
     gap> SCVertices(c);
     [ 1, 2, 3, 4 ]
     gap> SCRelabelTransposition(c,[1,2]);;
     gap> SCLabels(c);
     [ 2, 1, 3, 4 ]
     
  
  
  4.2-9 SCRename
  
  SCRename( complex, name )  method
  Returns:  true upon success, fail otherwise.
  
  Renames a polyhedral complex. The argument name has to be given in form of a
  string.
  
    Example  
     gap> c:=SCBdSimplex(5);;
     gap> SCName(c);
     "S^4_6"
     gap> SCRename(c,"mySphere");
     true
     gap> SCName(c);
     "mySphere"
     
  
  
  4.2-10 SCSetReference
  
  SCSetReference( complex, ref )  method
  Returns:  true upon success, fail otherwise.
  
  Sets  the literature reference of a polyhedral complex. The argument ref has
  to be given in form of a string.
  
    Example  
     gap> c:=SCBdSimplex(5);;
     gap> SCReference(c);
     #I  SCReference: complex lacks reference.
     fail
     gap> SCSetReference(c,"my 5-sphere in my cool paper");
     true
     gap> SCReference(c);
     "my 5-sphere in my cool paper"
     
  
  
  4.2-11 SCUnlabelFace
  
  SCUnlabelFace( complex, face )  method
  Returns:  a list upon success, fail otherwise.
  
  Computes the standard labeling of face in complex.
  
    Example  
     gap> c:=SCBdSimplex(3);;
     gap> SCRelabel(c,["a","bbb",5,[1,1]]);;
     gap> SCUnlabelFace(c,["a","bbb",5]);
     [ 1, 2, 3 ]
     
  
  
  
  4.3 Operations on objects of type SCPolyhedralComplex
  
  The   following   functions   perform   operations   on   objects   of  type
  SCPolyhedralComplex  and all of its subtypes. Most of them return simplicial
  complexes.  Thus,  this  section is closely related to the Sections 6.6 (for
  objects  of  type SCSimplicialComplex), ''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.
  
  4.3-1 SCAntiStar
  
  SCAntiStar( complex, face )  method
  Returns:  simplicial  complex of type SCSimplicialComplex upon success, fail
            otherwise .
  
  Computes  the  anti  star  of  face (a face given as a list of vertices or a
  scalar  interpreted  as  vertex) in complex, i. e. the complement of face in
  complex.
  
    Example  
     gap> SCLib.SearchByName("RP^2");     
     [ [ 3, "RP^2 (VT)" ], [ 635, "RP^2xS^1" ] ]
     gap> rp2:=SCLib.Load(last[1][1]);;
     gap> SCVertices(rp2);
     [ 1, 2, 3, 4, 5, 6 ]
     gap> SCAntiStar(rp2,1);
     [SimplicialComplex
     
      Properties known: Dim, FacetsEx, Name, Vertices.
     
      Name="ast([ 1 ]) in RP^2 (VT)"
      Dim=2
     
     /SimplicialComplex]
     gap> last.Facets;
     [ [ 2, 3, 4 ], [ 2, 4, 5 ], [ 2, 5, 6 ], [ 3, 4, 6 ], [ 3, 5, 6 ] ]
     
  
  
  4.3-2 SCLink
  
  SCLink( complex, face )  method
  Returns:  simplicial  complex of type SCSimplicialComplex upon success, fail
            otherwise.
  
  Computes  the  link  of face (a face given as a list of vertices or a scalar
  interpreted  as  vertex)  in  a polyhedral complex complex, i. e. all facets
  containing  face, reduced by face. if complex is pure, the resulting complex
  is  of  dimension  dim(complex)  -  dim(face)  -1.  If face is not a face of
  complex the empty complex is returned.
  
    Example  
     gap> SCLib.SearchByName("RP^2");     
     [ [ 3, "RP^2 (VT)" ], [ 635, "RP^2xS^1" ] ]
     gap> rp2:=SCLib.Load(last[1][1]);;
     gap> SCVertices(rp2);
     [ 1, 2, 3, 4, 5, 6 ]
     gap> SCLink(rp2,[1]);
     [SimplicialComplex
     
      Properties known: Dim, FacetsEx, Name, Vertices.
     
      Name="lk([ 1 ]) in RP^2 (VT)"
      Dim=1
     
     /SimplicialComplex]
     gap> last.Facets;
     [ [ 2, 3 ], [ 2, 6 ], [ 3, 5 ], [ 4, 5 ], [ 4, 6 ] ]
     
  
  
  4.3-3 SCLinks
  
  SCLinks( complex, k )  method
  Returns:  a  list  of  simplicial complexes of type SCSimplicialComplex upon
            success, fail otherwise.
  
  Computes  the  link  of  all  k-faces  of the polyhedral complex complex and
  returns  them  as  a  list  of simplicial complexes. Internally calls SCLink
  (4.3-2) for every k-face of complex.
  
    Example  
     gap> c:=SCBdSimplex(4);;
     gap> SCLinks(c,0);
     [ [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="lk([ 1 ]) in S^3_5"
          Dim=2
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="lk([ 2 ]) in S^3_5"
          Dim=2
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="lk([ 3 ]) in S^3_5"
          Dim=2
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="lk([ 4 ]) in S^3_5"
          Dim=2
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="lk([ 5 ]) in S^3_5"
          Dim=2
         
         /SimplicialComplex] ]
     gap> SCLinks(c,1);
     [ [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="lk([ 1, 2 ]) in S^3_5"
          Dim=1
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="lk([ 1, 3 ]) in S^3_5"
          Dim=1
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="lk([ 1, 4 ]) in S^3_5"
          Dim=1
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="lk([ 1, 5 ]) in S^3_5"
          Dim=1
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="lk([ 2, 3 ]) in S^3_5"
          Dim=1
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="lk([ 2, 4 ]) in S^3_5"
          Dim=1
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="lk([ 2, 5 ]) in S^3_5"
          Dim=1
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="lk([ 3, 4 ]) in S^3_5"
          Dim=1
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="lk([ 3, 5 ]) in S^3_5"
          Dim=1
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="lk([ 4, 5 ]) in S^3_5"
          Dim=1
         
         /SimplicialComplex] ]
     
  
  
  4.3-4 SCStar
  
  SCStar( complex, face )  method
  Returns:  simplicial  complex of type SCSimplicialComplex upon success, fail
            otherwise .
  
  Computes  the  star  of face (a face given as a list of vertices or a scalar
  interpreted  as  vertex)  in  a polyhedral complex complex, i. e. the set of
  facets of complex that contain face.
  
    Example  
     gap> SCLib.SearchByName("RP^2");     
     [ [ 3, "RP^2 (VT)" ], [ 635, "RP^2xS^1" ] ]
     gap> rp2:=SCLib.Load(last[1][1]);;
     gap> SCVertices(rp2);
     [ 1, 2, 3, 4, 5, 6 ]
     gap> SCStar(rp2,1);
     [SimplicialComplex
     
      Properties known: Dim, FacetsEx, Name, Vertices.
     
      Name="star([ 1 ]) in RP^2 (VT)"
      Dim=2
     
     /SimplicialComplex]
     gap> last.Facets;
     [ [ 1, 2, 3 ], [ 1, 2, 6 ], [ 1, 3, 5 ], [ 1, 4, 5 ], [ 1, 4, 6 ] ]
     
  
  
  4.3-5 SCStars
  
  SCStars( complex, k )  method
  Returns:  a  list  of  simplicial complexes of type SCSimplicialComplex upon
            success, fail otherwise.
  
  Computes  the  star  of  all  k-faces  of the polyhedral complex complex and
  returns  them  as  a  list  of simplicial complexes. Internally calls SCStar
  (4.3-4) for every k-face of complex.
  
    Example  
     gap> SCLib.SearchByName("T^2"){[1..6]};
     [ [ 4, "T^2 (VT)" ], [ 5, "T^2 (VT)" ], [ 9, "T^2 (VT)" ], [ 10, "T^2 (VT)" ],
       [ 18, "T^2 (VT)" ], [ 20, "(T^2)#2" ] ]
     gap> torus:=SCLib.Load(last[1][1]);; # the minimal 7-vertex torus
     gap> SCStars(torus,0); # 7 2-discs as vertex stars
     [ [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="star([ 1 ]) in T^2 (VT)"
          Dim=2
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="star([ 2 ]) in T^2 (VT)"
          Dim=2
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="star([ 3 ]) in T^2 (VT)"
          Dim=2
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="star([ 4 ]) in T^2 (VT)"
          Dim=2
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="star([ 5 ]) in T^2 (VT)"
          Dim=2
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="star([ 6 ]) in T^2 (VT)"
          Dim=2
         
         /SimplicialComplex], [SimplicialComplex
         
          Properties known: Dim, FacetsEx, Name, Vertices.
         
          Name="star([ 7 ]) in T^2 (VT)"
          Dim=2
         
         /SimplicialComplex] ]