Differences

This shows you the differences between two versions of the page.

--- user_guide:tutorials:apps_topaz [2019/01/25 09:38] – ↷ Page moved from user_guide:apps_topaz to user_guide:tutorials:apps_topaz oroehrig
+++ user_guide:tutorials:apps_topaz [2019/02/11 23:09] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
-===== Introduction to topaz =====
+{{page>.:latest:@FILEID@}}
-**This tutorial is also available as a {{ user_guide:apps_topaz.ipynb |jupyter notebook}} for polymake 3.1.**
-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.
-First, we have to make ''topaz'' the current application. For this you can either start ''polymake'' with the option ''-A topaz'',
-<code>
-polymake -A topaz
-</code>
-or, if you've already started ''polymake'', type
-<code>
-polytope > application 'topaz';
-</code>
-in the ''polymake'' shell.
-==== Simplicial complexes ====
-The most important object of the ''topaz'' application is the simplicial complex. There are several ways of obtaining one.
-===From faces===
-For example, you can specify some faces of the complex. Pass them as an Array< Set<Int> >:
-<code>
-topaz > $s = new SimplicialComplex(INPUT_FACES=>[[0],[0,1],[1,2,3]]);
-</code>
-{{ user_guide:small_complex.png?400|}}
-As you can see, redundancies are allowed -- [0] is not a facet of the complex, and thus not necessary for encoding $s. You can compute the inclusion maximal faces like this:
-<code>
-topaz > print $s->FACETS;
-{0 1}
-{1 2 3}
-</code>
-You can also pass the FACETS to the constructor, but be aware that in that case the vertices must be numbered increasingly starting with 0 and redundancies are prohibited.
-Take a look at your complex using
-<code>
-topaz > $s->VISUAL;
-</code>
-For more information on visualizing simplicial complex, see the section below.
-{{user_guide:face_lattice.png?200 |}}''polymake'' can compute the Hasse diagram of a simplicial complex (watch out, this gets really large for large complexes!). To print all the faces of the complex together with their rank in the face lattice, do this:
-<code>
-topaz >print $s->HASSE_DIAGRAM->DECORATION;
-({-1} 4)
-({0 1} 2)
-({1 2 3} 3)
-({0} 1)
-({1} 1)
-({1 2} 2)
-({1 3} 2)
-({2 3} 2)
-({} 0)
-({2} 1)
-({3} 1)
-</code>
-The first entry of each pair denotes the face, the second is the rank. The ''{-1}''-node is a dummy representing the whole complex. the ''{}''-node is the empty face. If you want to look at a pretty graph representation, try the visualization:
-<code>
-topaz > $s->VISUAL_FACE_LATTICE;
-</code>
-===Using clients===
-There are several clients that construct common simplicial complexes (for a comprehensive list, see the [[release_docs:latest/topaz.html|topaz documentation]]). An example is the torus client:
-<code>
-topaz > $t = torus();
-</code>
-Of course, ''polymake'' can compute the reduced integer homology groups of a simplicial complex, so we can convice ourselves this is a torus:
-<code>
-topaz > print $t->MANIFOLD;
-topaz > print $t->HOMOLOGY;
-({} 0)
-({} 2)
-({} 1)
-</code>
-The ''i''-th line represents the i-th homology module. The curly braces contain torsion coefficients with multiplicity, the second pair entry denotes the Betti number. The empty curly braces indicate that $t is torsion-free. You can see a non-empty torsion group here (using the ''rows_numbered'' client for a pretty print with the corresponding dimensions):
-<code>
-topaz > print rows_numbered( real_projective_plane()->HOMOLOGY );
-:{} 0
-:{(2 1)} 0
-:{} 0
-</code>
-As expected, the first homology group has torsion coefficient 2 with multiplicity 1 and all Betti numbers are zero.
-===As boundary complex===
-If your complex is a pseudo-manifold, you can obtain a new complex from its boundary. For example, this produces a triangulation of the 2-sphere:
-<code>
-topaz > $bs = simplex(3)->BOUNDARY;
-topaz > print $bs->SPHERE;
-</code>
-===Triangulating polytopes===
-The triangulation of a polytope is a simplicial complex, too. The ''TRIANGULATION'' gets stored in a property of the polytope. We use the ''cube'' client from the ''polytope'' application to demonstrate:
-<code>
-topaz > $c = polytope::cube(3);
-topaz > $tc = $c->TRIANGULATION;
-topaz > print $tc->FACETS;
-{0 1 2 4}
-{1 2 3 4}
-{1 3 4 5}
-{2 3 4 6}
-{3 4 5 6}
-{3 5 6 7}
-</code>
-==== Geometric realizations ====
-The ''topaz'' application is primarily designed to deal with abstract simplicial complexes that do not come with coordinates for an embedding in euclidean space. There is a special object subtype named ''GeometricSimplicialComplex'' that has extra properties for dealing with coodinates.
-You can pass the coordinates to the constructor. Take care to choose an embedding without crossings!
-<code>
-topaz > $s = new GeometricSimplicialComplex(INPUT_FACES=>[[0],[0,1],[1,2,3]], COORDINATES=>[[1,0],[1,1],[0,2],[2,2]]);
-</code>
-Some clients produce complexes with geometric realization...
-<code>
-topaz > $b = ball(3);
-topaz > # print a dense representation of the sparse matrix
-topaz > print dense( $b->COORDINATES );
-0 0
-0 0
-1 0
-0 1
-</code>
-...some others provide the option ''geometric_realization'' so you can decide whether to invest the extra computing time.
-<code>
-topaz > $bs = barycentric_subdivision($b,geometric_realization=>1);
-</code>
-Again, see the [[release_docs:latest/topaz.html|topaz documentation]] for a comprehensive list.
-==== Visualization ====
-Visualization of simplicial complexes uses the ''VISUAL'' property. Check out
-<code>
-topaz > help 'objects/SimplicialComplex/methods/Visualization/VISUAL';
-</code>
-{{ user_guide:ball_triang.png?300|}}
-for a list of available options and this [[visual_tutorial|tutorial]] for a general intro to visualization in polymake.
-If your complex is of dimension three or lower, you can visualize a geometric realization together with the ''GRAPH'' of the complex using the ''VISUAL'' property. Note that if your complex is not a ''GeometricSimplicialComplex'', ''polymake'' will use the spring embedder to find an embedding of the graph of the complex, which is not guaranteed to result in an intersection-free visualization.
-<code>
-topaz > $bs->VISUAL;
-</code>
-You should give the ''explode'' feature of jReality a try -- it gives a good (and pretty!) overview of the object. You can find it in the left slot of the jReality interface.
-{{user_guide:ball_triang_pink.png?250 |}} ''topaz'' may also visualize distinguished subcomplexes or just sets of faces with different decorations (colors, styles, etc.). For example, to highlight the fourth facet of ''$bs'' in pink, do this:
-<code>
-topaz > $a = new Array<Set<Int>>(1); $a->[0] = $bs->FACETS->[4];
-topaz > $bs->VISUAL->FACES($a, FacetColor => 'pink');
-</code>
-The same can be used for the visualization of the face lattice. As an example, we have a look at a ''morse matching'' of the Klein bottle with its associated critical faces. In order to see the arrowheads in the picture clearly, you ought to use graphviz or svg to vizualize it.
-<code>
-topaz > $k =  klein_bottle();
-topaz > graphviz($k->VISUAL_FACE_LATTICE->MORSE_MATCHING->FACES($k->MORSE_MATCHING->CRITICAL_FACES));
-</code>
-{{ user_guide:kb_mm_faces.gif?400|}}
-Here the matching of faces is denoted by reversed red arrows and the critical faces are marked red. Check that the graph remains acyclic.
-For higher dimensional complexes that cannot be visualized in 3D, you can still have a look at the graphs while ignoring any specified coordinates by using ''VISUAL_GRAPH'', ''VISUAL_DUAL_GRAPH'', or ''VISUAL_MIXED_GRAPH''. An easy example:
-<code>
-topaz > polytope::cube(3)->TRIANGULATION->VISUAL_MIXED_GRAPH;
-</code>
-shows the primal and dual graph of the polytope together with an edge between a primal and a dual node iff the primal node represents a vertex of the corresponding facet of the dual node.
-{{ user_guide:cube_graph.png?600 |}}
-Visualization of the ''HASSE_DIAGRAM'' is possible via ''VISUAL_FACE_LATTICE''. It renders the graph in a .pdf file. You can even pipe the tikz code to whatever location using the ''tikz'' client:
-<code>
-tikz($s->VISUAL_FACE_LATTICE, File=>"/path/to/file.tikz");
-</code>