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.

    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

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.

## 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

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`

    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

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)"

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)"

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.