GAP (simpcomp) - Chapter 1: Introduction

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]

1 Introduction
1.1 What is new
1.2 simpcomp benefits
1.3 How to save time reading this document
1.4 Organization of this document
1.5 How to assure simpcomp works correctly
1.6 Controlling simpcomp log messages
1.7 How to cite simpcomp

### 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 [BBP+14] (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:

    gap> SCRunTest();
    simpcomp package test
    msecs: 7810
    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.14",
    	year   = "2022",
    	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.14,
    2022,
    \url{https://github.com/simpcomp-team/simpcomp}.

[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