chap1.txt

  
  1 Introduction
  
  simpcomp  is  a  GAP  package  that  provides  the user with functions to do
  calculations  and  constructions with simplicial complexes in the context of
  combinatorial  topology (see abstract). If possible, it makes use of the GAP
  packages  homology  [DHSW11]  by  J.-G. Dumas et al. and GRAPE [Soi12] by L.
  Soicher.
  
  Most parts of this manual can be accessed directly from within GAP using its
  internal help system.
  
  
  1.1 What is new
  
  simpcomp  is  a  package for working with simplicial complexes. It claims to
  provide the user with a broad spectrum of functionality regarding simplicial
  constructions.
  
  simpcomp allows the user to interactively construct complexes and to compute
  their  properties  in  the  GAP  shell.  Furthermore,  it makes use of GAP's
  expertise  in  groups and group operations. For example, automorphism groups
  and  fundamental  groups  of  complexes can be computed and examined further
  within  the  GAP  system. Apart from supplying a facet list, the user can as
  well  construct  simplicial  complexes  from  a  set  of  generators  and  a
  prescribed automorphism group -- the latter form being the common in which a
  complex  is  presented  in  a  publication. This feature is to our knowledge
  unique  to  simpcomp. Furthermore, simpcomp as of Version 1.3.0 supports the
  construction  of simplicial complexes of prescribed dimension, vertex number
  and  transitive  automorphism  group  as  described in [Lut03], [CK01] and a
  number of functions (function prefix SCSeries...) provide infinite series of
  combinatorial manifolds with transitive automorphism group.
  
  As  of  Version  1.4.0,  simpcomp  provides  the  possibility  to  perform a
  combinatorial  version  of  algebraic blowups, so-called simplicial blowups,
  for  combinatorial  4-manfolds  as  described  in  [SK11]  and [Spr11a]. The
  implementation  can  be  used  as  well to resolve isolated singularities of
  combinatorial  4-pseudomanifolds. It seems that this feature, too, is unique
  to simpcomp.
  
  Starting  from  Version  1.5.4,  simpcomp  comes with more efficient code to
  perform  bistellar  moves implemented in C (see function SCReduceComplexFast
  (9.2-15)). However, this feature is completely optional.
  
  
  1.2 simpcomp benefits
  
  The  origin  of  simpcomp  is  a  collection  of  scripts of the two authors
  [Eff11a],  [Spr11a]  that  provide  basic  and  often-needed  functions  and
  operations  for  working with simplicial complexes. Apart from some optional
  code  dealing  with  bistellar  moves  (see  Section  9  and  in  particular
  SCReduceComplexFast  (9.2-15)),  it is written entirely in the GAP scripting
  language,  thus giving the user the possibility to see behind the scenes and
  to customize or alter simpcomp functions if needed.
  
  The  main  benefit  when  working with simpcomp over implementing the needed
  functions  from  scratch  is  that  simpcomp  encapsulates  all  methods and
  properties  of a simplicial complex in a new GAP object type (as an abstract
  data  type).  This way, among other things, simpcomp can transparently cache
  properties   already   calculated,   thus   preventing   unnecessary  double
  calculations.  It  also  takes  care of the error-prone vertex labeling of a
  complex.  As  of  Version 1.5, simpcomp makes use of GAP's caching mechanism
  (as  described  in  [BL98])  to  cache  all known properties of a simplicial
  complex.  In  addition,  a customized data structure is provided to organize
  the complex library and to cache temporary information about a complex.
  
  simpcomp  provides  the  user with functions to save and load the simplicial
  complexes  to  and  from files and to import and export a complex in various
  formats  (e.g. from and to polymake/TOPAZ [GJ00], SnapPea [Wee99] and Regina
  [BBPo14] (via the SnapPea file format), Macaulay2 [GS], LaTeX, etc.).
  
  In  contrast  to  the  software  package  polymake [GJ00] providing the most
  efficient algorithms for each task in form of a heterogeneous package (where
  algorithms  are  implemented  in  various  languages), the primary goal when
  developing  simpcomp  was not efficiency (this is already limited by the GAP
  scripting language), but rather ease of use and ease of extensibility by the
  user   in   the  GAP  language  with  all  its  mathematical  and  algebraic
  capabilities.  Extending  simpcomp  is  possible  directly  from within GAP,
  without having to compile anything, see Chapter 18.
  
  
  1.3 How to save time reading this document
  
  The   core   component  in  simpcomp  is  the  newly  defined  object  types
  SCPropertyObject  and  its derived subtype SCSimplicialComplex. When working
  with  this  package it is important to understand how objects of these types
  can  be  created,  accessed and modified. The reader is therefore advised to
  first skim over the Chapters 3 and 5.
  
  The impatient reader may then directly skip to Chapter 17 to see simpcomp in
  action.
  
  The  next  advised  step  is  to  have  a look at the functions for creating
  objects of type SCSimplicialComplex, see the first section of Chapter 6.
  
  The rest of Chapter 6 contains most of the functions that simpcomp provides,
  except   for  the  functions  related  to  (co-)homology,  bistellar  flips,
  simplicial  blowups,  polyhedral  Morse  theory,  slicings  (discrete normal
  surfaces)  and  the  simplicial  complex  library  that are described in the
  Chapters   8  to  13.  Functions  for  the  more  general  GAP  object  type
  SCPolyhedralComplex are described in Chapter 4 .
  
  
  1.4 Organization of this document
  
  This manual accompanying simpcomp is organized as follows.
  
      Chapter  2 provides a short introduction into the theory of simplicial
        complexes and PL-topology.
  
      Chapter  3  gives  a short overview about the newly defined GAP object
        types simpcomp is working with.
  
      Chapter  4  is  devoted  to  the  description  of  the GAP object type
        SCPolyhedralComplex that is defined by simpcomp.
  
      Chapter  5  introduce  the  GAP  object  types SCSimplicialComplex and
        SCNormalSurface which are both derived from SCPolyhedralComplex.
  
      In  Chapter  6  functions  for  working  with simplicial complexes are
        described.
  
      Chapter  7  gives  an  overview  over  functions related to slicings /
        discrete normal surfaces.
  
      Chapter  8 describes the homology- and cohomology-related functions of
        simpcomp.
  
      Chapter 9 contains a description of the functions related to bistellar
        flips provided by simpcomp.
  
      In  Chapter  10 simplicial blowups and resolutions of singularities of
        combinatorial 4-pseudomanifolds are explained.
  
      In Chapter 11 polyhedral Morse theory is discussed.
  
      In  Chapter  13  the  simplicial  complex library and the input output
        functionality that simpcomp provides is described in detail.
  
      Chapter 15 contains descriptions of functions not fitting in the other
        chapters, such as the error handling and the email notification system
        of simpcomp.
  
      Chapter 16 contains a list of all property handlers allowing to access
        properties  of  a SCSimplicialComplex object, a SCNormalSurface object
        or  a  SCLibRepository  object  via  the  dot  operator (pseudo object
        orientation).
  
      Chapter  17  contains  the  transcript of a demo session with simpcomp
        showing  some  of  the  constructions and calculations with simplicial
        complexes that can also be used as a first overview of things possible
        with this package.
  
      Finally,  Chapter  18  focuses  on  the  description  of  the internal
        structure  of  simpcomp  and  deals  with  aspects  of  extending  the
        functionality of the package.
  
  
  1.5 How to assure simpcomp works correctly
  
  As  with  all  software,  it is important to test whether simpcomp functions
  correctly  on  your  system after installing it. GAP has an internal testing
  mechanism and simpcomp ships with a short testing file that does some sample
  computations and verifies that the results are correct.
  
  To  test  the  functionality  of simpcomp you can run the function SCRunTest
  (15.3-1) from the GAP console:
  
    Example  
    gap> SCRunTest();
    + test simpcomp package, Version 2.1.7
    + GAP4stones: 69988
    true
    gap> 
  
  
  SCRunTest  (15.3-1)  should return true, otherwise the correct functionality
  of simpcomp cannot be guaranteed.
  
  
  1.6 Controlling simpcomp log messages
  
  Note  that  the  verbosity of the output of information to the screen during
  calls  to functions of the package simpcomp can be controlled by setting the
  info level parameter via the function SCInfoLevel (15.1-1).
  
  
  1.7 How to cite simpcomp
  
  If  you  would like to cite simpcomp using BibTeX, you can use the following
  BibTeX  entry  for the current simpcomp version (remember to include the url
  package in your LaTeX document):
  
  @manual{simpcomp,
  	author = "Felix Effenberger and Jonathan Spreer",
  	title  = "{\tt simpcomp} - a {\tt GAP} toolkit for simplicial complexes,
  	          {V}ersion 2.1.7",
  	year   = "2017",
  	url    = "\url{https://github.com/simpcomp-team/simpcomp}",
  }
  
  If  you  are  not  using  BibTeX, you can use the following entry inside the
  bibliography environment of LaTeX.
  
  \bibitem{simpcomp}
  F.~Effenberger and J.~Spreer,
  \emph{{\tt simpcomp} -- a {\tt GAP} toolkit for simplicial complexes},
  Version 2.1.7, 
  2017,
  \url{https://github.com/simpcomp-team/simpcomp}.