howto.xml

<Chapter Label="chap:howto">
<Heading>Introduction</Heading>

<Package>simpcomp</Package> 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 <Package>homology</Package> <Cite Key="Dumas04Homology"/> by J.-G. Dumas et al. and <Package>GRAPE</Package> <Cite Key="Soicher06GRAPE"/> by L. Soicher.

<P/>

Most parts of this manual can be accessed directly from within &GAP; using its internal help system.


<Section Label="sec:whatisnew">
<Heading>What is new</Heading>

<Package>simpcomp</Package> is a package for working with simplicial complexes.  It claims to provide the user with a broad spectrum of functionality regarding simplicial constructions.   

<P/>

<Package>simpcomp</Package> 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 <Package>simpcomp</Package>. Furthermore, <Package>simpcomp</Package> as of Version 1.3.0 supports the construction of simplicial complexes of prescribed dimension, vertex number and transitive automorphism group as described in <Cite Key="Lutz03TrigMnfFewVertVertTrans"/>, <Cite Key="Casella01TrigK3MinNumVert"/> and a number of functions (function prefix <C>SCSeries...</C>) provide infinite series of combinatorial manifolds with transitive automorphism group.

<P/>


As of Version 1.4.0, <Package>simpcomp</Package> provides the possibility to perform a combinatorial version of algebraic blowups, so-called simplicial blowups, for combinatorial <M>4</M>-manfolds as described in <Cite Key="Spreer09CombPorpsOfK3"/> and <Cite Key="Spreer10Diss"/>. The implementation can be used as well to resolve isolated singularities of combinatorial <M>4</M>-pseudomanifolds. It seems that this feature, too, is unique to <Package>simpcomp</Package>.

<P/>

Starting from Version 1.5.4, <Package>simpcomp</Package> comes with more efficient code to perform bistellar moves implemented in <C>C</C> (see function <Ref Func="SCReduceComplexFast" />). However, this feature is completely optional.

</Section>

<Section Label="sec:whysimpcomp">
<Heading><Package>simpcomp</Package> benefits</Heading>

The origin of <Package>simpcomp</Package> is a collection of scripts of the two authors <Cite Key="Effenberger10Diss" />, <Cite Key="Spreer10Diss" /> 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 <Ref Chap="chap:bistellar"/> and in particular <Ref Func="SCReduceComplexFast" />), 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 <Package>simpcomp</Package> functions if needed. 

<P/>

The main benefit when working with <Package>simpcomp</Package> over implementing the needed functions from scratch is that <Package>simpcomp</Package> 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, <Package>simpcomp</Package> 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, <Package>simpcomp</Package> makes use of &GAP;'s caching mechanism (as described in <Cite Key="Breuer98GAP4TypeSystem"/>) 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.

<P/>

<Package>simpcomp</Package> 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 <Package>polymake/TOPAZ</Package> <Cite Key="Joswig00Polymake"/>,  <Package>SnapPea</Package> <Cite Key="SnapPea"/> and <Package>Regina</Package> <Cite Key="regina"/> (via the <Package>SnapPea</Package> file format), <Package>Macaulay2</Package> <Cite Key="M2"/>, LaTeX, etc.). 

<P/>

In contrast to the software package <Package>polymake</Package> <Cite Key="Joswig00Polymake"/> 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 <Package>simpcomp</Package> 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 <Package>simpcomp</Package> is possible directly from within &GAP;, without having to compile anything, see Chapter <Ref Chap="chap:internals"/>.<P/>

</Section>

<Section Label="sec:howtoread">
<Heading>How to save time reading this document</Heading>

The core component in <Package>simpcomp</Package> is the newly defined object types <C>SCPropertyObject</C> and its derived subtype <C>SCSimplicialComplex</C>. 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 <Ref Chap="chap:objTypes"/> and <Ref Chap="chap:complex"/>.

<P/>

The impatient reader may then directly skip to Chapter <Ref Chap="chap:demo"/> to see <Package>simpcomp</Package> in action.

<P/>

The next advised step is to have a look at the functions for creating objects of type <C>SCSimplicialComplex</C>, see the first section of Chapter <Ref Chap="chap:scfunc"/>. 
<P/>

The rest of Chapter <Ref Chap="chap:scfunc"/> contains most of the functions that <Package>simpcomp</Package> 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 <Ref Chap="chap:homology"/> to <Ref Chap="chap:libio"/>. Functions for the more general &GAP; object type <C>SCPolyhedralComplex</C> are described in Chapter <Ref Chap="chap:polyhedralcomplex"/> .

</Section>

<Section Label="sec:howtoorg">
<Heading>Organization of this document</Heading>

This manual accompanying <Package>simpcomp</Package> is organized as follows.

<List>
	<Item>
	Chapter <Ref Chap="chap:theory"/> provides a short introduction into the theory of simplicial complexes and PL-topology.
	</Item>
	
	<Item>
	Chapter <Ref Chap="chap:objTypes"/> gives a short overview about the newly defined &GAP; object types <Package>simpcomp</Package> is working with.
	</Item>
	
	<Item>
	Chapter <Ref Chap="chap:polyhedralcomplex"/> is devoted to the description of the &GAP; object type <C>SCPolyhedralComplex</C> that is defined by <Package>simpcomp</Package>.
	</Item>
	
	<Item>
	Chapter <Ref Chap="chap:complex"/>  introduce the &GAP; object types <C>SCSimplicialComplex</C> and <C>SCNormalSurface</C> which are both derived from <C>SCPolyhedralComplex</C>.
	</Item>
	
	<Item>
	In Chapter <Ref Chap="chap:scfunc"/> functions for working with simplicial complexes are described. 
	</Item>
	
	<Item>
	Chapter <Ref Chap="chap:NormSurfFunc"/> gives an overview over functions related to slicings / discrete normal surfaces.
	</Item>

	<Item>
	Chapter <Ref Chap="chap:homology"/> describes the homology- and cohomology-related functions of <Package>simpcomp</Package>. 
	</Item>
	
	<Item>
	Chapter <Ref Chap="chap:bistellar"/> contains a description of the functions related to bistellar flips provided by <Package>simpcomp</Package>. 
	</Item>
	
	<Item>
	In Chapter <Ref Chap="chap:blowups"/> simplicial blowups and resolutions of singularities of combinatorial <M>4</M>-pseudomanifolds are explained. 
	</Item>
	
	<Item>
	In Chapter <Ref Chap="chap:morse"/> polyhedral Morse theory is discussed.
	</Item>
	
	<Item>
	In Chapter <Ref Chap="chap:libio"/> the simplicial complex library and the input output functionality that <Package>simpcomp</Package> provides is described in detail. 
	</Item>
	
	<Item>
	Chapter <Ref Chap="chap:misc"/> contains descriptions of functions not fitting in the other chapters, such as the error handling and the email notification system of <Package>simpcomp</Package>. 
	</Item>
	
	
	<Item>
	Chapter <Ref Chap="chap:prophandler"/> contains a list of all property handlers allowing to access properties of a <C>SCSimplicialComplex</C> object, a <C>SCNormalSurface</C> object or a <C>SCLibRepository</C> object via the dot operator (pseudo object orientation).
	</Item>
	
	<Item>
	Chapter <Ref Chap="chap:demo"/> contains the transcript of a demo session with <Package>simpcomp</Package> 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.
	</Item>
	
	<Item>
	Finally, Chapter <Ref Chap="chap:internals"/> focuses on the description of the internal structure of <Package>simpcomp</Package> and deals with aspects of extending the functionality of the package. 
	</Item>
</List>

</Section>


<Section Label="sec:testsimpcomp">
<Heading>How to assure <Package>simpcomp</Package> works correctly</Heading>
As with all software, it is important to test whether <Package>simpcomp</Package> functions correctly on your system after installing it. &GAP; has an internal testing mechanism and <Package>simpcomp</Package> ships with a short testing file that does some sample computations and verifies that the results are correct.<P/>

To test the functionality of <Package>simpcomp</Package> you can run the function <Ref Func="SCRunTest"/> from the &GAP; console:

<Log>
gap> SCRunTest();
+ test simpcomp package, Version 2.1.7
+ GAP4stones: 69988
true
gap> 
</Log>

<Ref Func="SCRunTest"/> should return <K>true</K>, otherwise the correct functionality of simpcomp cannot be guaranteed.
</Section>


<Section Label="sec:logging">
<Heading>Controlling <Package>simpcomp</Package> log messages</Heading>

Note that the verbosity of the output of information to the screen during calls to functions of the package <Package>simpcomp</Package> can be controlled by setting the info level parameter via the function <Ref Func="SCInfoLevel" />.

</Section>


<Section Label="sec:citesimpcomp">
<Heading>How to cite <Package>simpcomp</Package></Heading>

If you would like to cite <Package>simpcomp</Package> using BibTeX, you can use the following BibTeX entry for the current <Package>simpcomp</Package> version (remember to include the <Code>url</Code> package in your &LaTeX; document):

<Verb>
@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}",
}
</Verb>
	
If you are not using BibTeX, you can use the following entry inside the bibliography environment of LaTeX.

<Verb>
\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}.
</Verb>
</Section>


</Chapter>