This tutorial tries to give the user a first idea about the features of the topaz application of polymake. We take a look at a variety of small examples. The text contains commands to be given to the polymake system (preceded by a '>') along with the output. Commands and output are displayed in typewriter type.

A first example to get started: building spheres

One way to construct a triangulated d-sphere is to start with a d-ball and add the cone over the boundary. Let's do so and let d = 2. (We are just warming up.) To make things not too simple, we will use a triangulated square as a 2-ball. The vertices of the square are numbered 0, 1, 2, and 3, and our complex consists of the facets {0 1 3} and {0 2 3}. In topaz any simplicial complex is encoded as its set of FACETS, the inclusion maximal faces. Pay attention that the vertices must be numbered consecutively starting with 0 and that no redundancies are allowed. Thus we create a text file my_2ball.top consisting of the following three lines:

FACETS
{0 1 3}
{0 2 3} 

Alternatively you may use the cube_complex client:

> cube_complex my_2ball.top 1 1 

Now the question of computing the boundary arises. Since a simplex is a pseudo manifold, this question is answered easily. We select all ridges contained in one facet only. polymake not only does this for us, it also checks first, if the complex actually is a pseudo manifold.

> polymake -A topaz my_2ball.top BOUNDARY_OF_PSEUDO_MANIFOLD
BOUNDARY_OF_PSEUDO_MANIFOLD
{0 1}
{1 3}
{0 2}
{2 3} 

The option -A topaz tells polymake that we want to use the topaz application. Once having seen it, polymake remembers that our file is a topaz file, so you may omit this option by all subsequent computations.

But let's have a look at the file my_2ball.top once polymake is finished.

FACETS
{0 1 3}
{0 2 3}

DIM
2

PURE
1

PSEUDO_MANIFOLD
1

HASSE_DIAGRAM
1 3 8 12
({} {})
({0 1 3} {0})
({0 2 3} {0})
({0 1} {1})
({0 3} {1 2})
({1 3} {1})
({0 2} {2})
({2 3} {2})
({0} {3 4 6})
({1} {3 5})
({3} {4 5 7})
({2} {6 7})
({} {8 9 10 11})

BOUNDARY_OF_PSEUDO_MANIFOLD
{0 1}
{1 3}
{0 2}
{2 3} 

We see the section FACETS, which we produced ourselves, and a lot of additional information computed for us. (Do not worry about the representation of the sections. The most curious and impatient can find a precise explanation by clicking on the section headers.) Actually, polymake has done rather a lot. In order to verify that my_2ball.top is a pseudo manifold, polymake computed the HASSE_DIAGRAM, the dimension DIM and that the complex is PURE. With all that information, computing the boundary is easy: the Hasse diagram tells us, which ridges are contained in one facet only.

Next we want to compute the cone over the boundary. The result will be a new object, unlike the boundary, which can be viewed as a property of my_2ball.top. Whenever we want to produce a new simplicial complex, we do not call the polymake script, but call the construction program, in our case it will be cone, directly.

> cone my_cone.top my_2ball.top BOUNDARY_OF_PSEUDO_MANIFOLD 

The command line first names the client we are using, followed by the output file, input file and the section we want to use for the construction. For any client program, if in doubt how to use it, just type the client's name and press return.

Finally we have to complete the construction of the sphere by computing the union of the ball and the cone over its boundary. The t_union client relies on the VERTEX_LABELS to determine which vertices get identified with each other. Since we did not specify any labels, they are just induced by the vertex numbering. The vertex labels of my_cone.top are the ones induced by BOUNDARY_OF_PSEUDO_MANIFOLD, except for the apex which topaz labels uniquely, in our case apex_0. If we now construct the union, topaz identifies the vertices correctly.

> t_union my_2sphere.top my_2ball.top my_cone.top 

In order to verify what we have done, lets have a look at the HOMOLOGY of the complex. Since my_2sphere.top is an oriented pseudo manifold of dimension 2, the homology suffices to prove that it is a sphere.

> polymake my_2sphere.top HOMOLOGY
HOMOLOGY
({} 0)
({} 0)
({} 1) 

The application topaz computes the reduced homology. Therefore the output tells us that H0 and H1 are trivial and H2 is isomorphic to Z.

Still not convinced? Then lets have a look at the complex. After all, a 2-sphere is embeddable in R3. All we need are coordinates for the vertices. Note that in contrast to the polytope application, we do not use homogeneous coordinates for the GEOMETRIC_REALIZATION of a simplicial complex. Add the following information to the my_2sphere.top file.

simplicial 2-sphere
GEOMETRIC_REALIZATION
0 0 0
0 0 2
0 2 0
0 2 2
1 1 1 

And let polymake visualize it.

> polymake my_2sphere.top VISUAL 

If you call polymake requesting the method VISUAL, polymake visualizes the GRAPH and the facets of the complex using the GEOMETRIC_REALIZATION as embedding. If the dimension of the geometric realization is greater than three, polymake tries to embed the graph using the home-made spring embedder. The standard tool for visualization is JavaView, which is fully interactive. For instance, it allows you to rotate or zoom into your complex. There are some other visualizations available which will be introduce later.

Last but not least, topaz can verify that the complex is a sphere. If the dimension is smaller than three a deterministic algorithm is used. In higher dimensions topaz uses a heuristic approach to try to verify if the complex is a sphere.

> polymake my_2sphere.top SPHERE
SPHERE
1 

But let us build a different sphere. We will use the boundary of a 3-ball. Since topaz views the boundary of a complex as a property of the original complex rather than a complex in its own right, we must use the extract_subcomplex client to get our sphere.

> ball my_3ball.top 3
> extract_subcomplex my_2sphere.top my_3ball.top BOUNDARY_OF_PSEUDO_MANIFOLD 
simplicial 3-sphere

It is time to get a little more ambitious. So we will build a 3-sphere using the suspension of my_2sphere.top to do so.

> suspension my_3sphere.top my_2sphere.top FACETS
> polymake my_3sphere.top HOMOLOGY
HOMOLOGY
({} 0)
({} 0)
({} 0)
({} 1)

> polymake my_3sphere.top VISUAL 

Let us have a closer look at the visualization of the complex. For each facet all faces of dimension two and smaller build a distinct JavaView geometry. Try Method -> Effect -> Explode Group of Geometries in the JavaView menu. In the image you can see the facets intersecting each other and the graph of the complex.

All this is rather complicated if you are interested in just any triangulated d-sphere. Therefore topaz can produce a sphere for you. The client sphere uses the boundary complex of a simplex, for example

> sphere sphere3.top 3 

Another class of simplicial spheres are the boundary complexes of simplicial polytopes, leading us to the next section.

boundary complex simplicial polytope

Moving in between applications

There is a strong connection between (simplicial) polytopes and simplicial complexes: The boundary_complex of a simplicial polytope (or the triangulated boundary of an arbitrary polytope) is a simplicial complex, and for a given simplicial complex one might ask, whether there exists a polytope with the complex as its boundary. Alternatively topaz computes the crosscut_complex and the triangulation_complex.

We will use polytopes generated by a random point distribution on the unit sphere to demonstrate this connection.

> rand_sphere rand_sphere.poly 3 10
> boundary_complex rand_sphere.top rand_sphere.poly
> polymake rand_sphere.top VISUAL

Again, to verify what we have done, lets compare our result with the original polytope.

> polymake rand_sphere.poly VISUAL

Any triangulated surface is in particular a simplicial complex, hence the client surf2top. To observe its effect, try to convert the quad_surface.surf example from the surface tutorial.

> surf2top quad_surface.triang.top quad_surface.surf
> polymake quad_surface.triang.top VISUAL

Other constructions

The topaz application is of course not limited to triangulated balls and spheres. Any simplicial complex, represented as its set of FACETS can be worked with. In fact, topaz knows a few standard constructions. So, let's try another example, a subdivided tetrahedra. Again, topaz provides us with the means to construct such a complex.

> ball ball.top 3
> barycentric_subdivision bs_ball.top ball.top -geom_real 
barycentric subdivided tetrahedra

The -geom_real flag tells the client to compute the GEOMETRIC_REALIZATION. Since computing the geometric realization can be done, yet requires some time, the client does it only when explicitly asked for. If you would like to know more about visualization and the topaz application, have a look at the following section. But for now just have a look at this. Again try Method -> Effect -> Explode Group of Geometries in the JavaView menu.

> polymake bs_ball.top VISUAL 

But we promised something different from balls and spheres, so try

> cube_complex my_pile.top 3 3
> polymake my_pile.top VERTEX_LABELS VISUAL
VERTEX_LABELS
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 

and add the following information to the file (you may choose any name for the gluing section):

GLUE
{0 3 12 15}
{1 13}
{2 14}
{4 7}
{8 11} 

The client glue_induced_subcomplexes replaces the vertices in each glueing set by one representative (with the smallest number) and removes any redundancies which may result from this identification. If two sets are not disjoint, the client replaces them by their union to guarantee transitivity. Vertices not contained in any of the glueing sets are considered to be in a glueing set by themselves, therefore will not be glued to any other. The result is a torus.

> glue_induced_subcomplexes my_torus.top my_pile.top GLUE 

To get a realy good look at our torus let's add coordinated to my_torus.top

torus
GEOMETRIC_REALIZATION
0 0 0
0 0 8
0 7 4
1 1 2
1 1 6
1 5 4
2 0 0
2 0 8
2 7 4 

and have a look at it.

> polymake my_torus.top VISUAL 

Of course topaz knows about the torus and other surfaces like the klein_bottle or the projective_plane. So lets try the following

> projective_plane pp.top
> connected_sum my_surface.top my_torus.top pp.top
> polymake my_surface.top MANIFOLD HOMOLOGY
MANIFOLD
1

HOMOLOGY
({} 0)
({(2 1)} 2)
({} 0) 

and we end up with a non orientable surface of genus 3. Again we could have let topaz do the work by calling the surface client. (The "-3" indicates that we want a non orientable surface homeomorphic to the connected sum of three projective planes.)

> surface surface.top -3
> polymake surface.top MANIFOLD HOMOLOGY
MANIFOLD
1

HOMOLOGY
({} 0)
({(2 1)} 2)
({} 0) 

About visualizing simplicial complexes

In the previous sections of the tutorial we tried to provide images for most of the example. However, the topaz application is primarily designed to work with abstract simplicial complexes. Therefore constructions only deal with coordinates if only little extra computation is involved. Otherwise topaz's means to visualize are limited. Visualization gets increasingly harder for complexes embedded in R4 or higher dimensions. Some clients like boundary_complex or cube_complex provide us with coordinates or compute them if possible (most likely you will have to specify the -geom_real flag in order to make the client produce coordinates). Otherwise all the topaz application can do is try to compute coordinates by using the spring embedder for the graph of the complex.

To visualize the complex use

> polymake -A topaz file.top VISUAL 
pile with boundary

and you will see the GRAPH and the facets embedded in R3 using the GEOMETRIC_REALIZATION, if it has dimension three or smaller. Otherwise the spring embedder is used. For each facet all faces of dimension two and smaller build a distinct JavaView geometry. Try Method -> Effect -> Explode Group of Geometries in the JavaView menu to see how the facets fit together. This visualization can sometimes give an insight, even if the complexes cannot be embedded in R3.

Calling polymake requesting VISUAL_GRAPH , VISUAL_DUAL_GRAPH, or VISUAL_MIXED_GRAPH embeds the graph in R3 using the spring embedder yet ignores any specified coordinates.

topaz may also visualize distinguished subcomplexes or just sets of faces with different decorations (colors, styles, etc.). Say the property specifying the subcomplex is called MY_SUBCOMPLEX, you call polymake requesting "VISUAL->SUBCOMPLEX(MY_SUBCOMPLEX)". The effect is similar to what you see when calling VISUAL, only that the facets of the subcomplex are added as well. For example, try to visualize a 3-dimensional cube_complex and its BOUNDARY_OF_PSEUDO_MANIFOLD.

> cube_complex my_pile.top 1 1 1
> polymake my_pile.top "VISUAL->SUBCOMPLEX(BOUNDARY_OF_PSEUDO_MANIFOLD)"

The facets of the subcomplex are colored blue. Again, you may use Method -> Effect -> Explode Group of Geometries in the JavaView menu.

Alternatively to visualizing an entire subcomplex, topaz can visualize distinguished faces only. For an example, let us visualize our torus from above, its MORSE_MATCHING, and the critical faces of the Morse matching, the MORSE_MATCHING_CRITICAL_FACES.

> polymake my_torus.top "VISUAL->MORSE_MATCHING->FACES(MORSE_MATCHING_CRITICAL_FACES)"
Mores matching

The critical faces are colored red, the colors of the arrows interpolate in between orange (matching vertices to edges) and purple (matching (d-1)-faces to facets). As one expects, we have one critical vertex, two critical edges (the first homology group is isomorphic to Z2), and one critical triangle. In contrast to visualizing a subcomplex, where each facet of the subcomplex is drawn with all its faces, here only the distinguished faces are added to the visualization.

If visualization is not successful (e.g. the dimension of the complex is to high or there are no coordinates available), you may have a look at the face lattice. We choose a klein_bottle to demonstrate this visualization tool.

> klein_bottle kb.top
> polymake kb.top "VISUAL_FACE_LATTICE->MORSE_MATCHING->FACES(MORSE_MATCHING_CRITICAL_FACES)"
Klein bottle

Here the matching of faces is denoted by reversed red arrows and the critical faces are marked red. As in the previous example of the torus, we have one critical vertex, two critical edges (the first homology group is isomorphic to Z + Z2), and one critical triangle. Check that the graph remains acyclic. Of course, as with VISUAL, you may also add a SUBCOMPLEX to the visualization of the face lattice: The sublattice, that is all faces and their inclusions corresponding to the subcomplex, is colored blue.

As described above, polymake uses it's spring embedder if VISUAL is called and no three-dimensional coordinates are available. As the default, the primal graph is used. However, in order to use the neighborhood information encoded in the primal graph as well as the neighborhood information encoded in the dual graph (that is neighboring vertices and neighboring facets), you may ask polymake to use the MIXED_GRAPH for the spring embedding by calling "VISUAL(mixed_graph=>1)" . The mixed-graph is composed of all nodes and edges of the primal and the dual graph and an additional edge is added between a primal and a dual node if the vertex corresponding to the primal node lies in the facet corresponding to the dual node.