documentation:master:topaz

Differences

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


documentation:master:topaz [2024/03/21 05:58] (current) – created - external edit 127.0.0.1
Line 1: Line 1:
 +====== application topaz ======
 + The __TOP__ology __A__pplication __Z__oo deals with abstract simplicial complexes. A complex is given as a list of facets.  You can ask for its global properties ([[.:topaz:SimplicialComplex#MANIFOLD |manifold recognition]], [[.:topaz:SimplicialComplex#HOMOLOGY |homology groups]], etc.),  explore the local vertex environment ([[.:topaz#star_subcomplex |stars]], [[.:topaz#link_subcomplex |links]], etc.),  and make a lot of constructions. The visualization means are constrained, as they are mostly based on the ''[[.:topaz:SimplicialComplex#GRAPH |GRAPH]]'' (1-skeleton) of a complex.
 +
 +imports from:
 +    * application [[.:common|common]]
 +    * application [[.:graph|graph]]
 +uses:
 +    * application [[.:group|group]]
 +    * application [[.:ideal|ideal]]
 +
 +===== Objects =====
 +  ** ''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]'':\\  A geometric simplicial complex, i.e., a simplicial complex with a geometric realization. //Scalar// is the numeric data type used for the coordinates.
 +  ** ''[[.:topaz:GrassPluckerCertificate |GrassPluckerCertificate]]'':\\  This object encodes a decorated graph that certifies that a given simplicial complex is not realizable as the boundary of a convex polytope. The simplicial complex itself should either be a simplicial sphere, or an oriented simplicial complex with boundary. In the latter case, each component of the boundary will be coned over by a new point, and the resulting complex should then be a simplicial sphere.  (This is important when handling Criado & Santos's topological prismatoids, for example.) The nodes of the graph are decorated with Grassmann-Plücker polynomials, and the edges with "undetermined solids", ie, solids whose orientation can vary according to the realization. The point of the certificate is that no matter how these undetermined solids are oriented, there will always be some Grassmann-Plücker polynomial in the tree all of whose terms are positive. But this contradicts realizability, because the matrix of homogeneous coordinates of any putative convex realization of a d-sphere on n vertices determines a point in the Grassmann manifold G(d,n), which means that all GP-polynomials should vanish -- but the special one can't, because all its terms are positive.
 +  ** ''[[.:topaz:HyperbolicSurface |HyperbolicSurface]]'':\\ A hyperbolic surface (noncompact, finite area) is given by a triangulation ''[[.:topaz:HyperbolicSurface#DCEL |DCEL]]'' (the topological data) and ''[[.:topaz:HyperbolicSurface#PENNER_COORDINATES |PENNER_COORDINATES]]'' (the metric data).
 +  ** ''[[.:topaz:MorseMatching |MorseMatching]]'':\\  A Morse matching is a reorientation of the arcs in the Hasse diagram of a simplicial complex such that at most one arc incident to each face is reoriented (matching condition) and the resulting orientation is acyclic (acyclicity condition). Morse matchings capture the main structure of discrete Morse functions, see
 +  > Robin Forman: Morse Theory for Cell-Complexes,
 +  > Advances in Math., 134 (1998), pp. 90-145.
 +  .. This property is computed by one of two heuristics. The default heuristic is a simple greedy algorithm ([[.:topaz:SimplicialComplex |greedy]]). The alternative is to use a canceling algorithm due to Forman ([[.:topaz:SimplicialComplex |cancel]]) or both ([[.:topaz:SimplicialComplex |both]]) together. Note that the computation of a Morse matching of largest size is NP-hard. See
 +  > Michael Joswig, Marc E. Pfetsch: Computing Optimal Morse Matchings
 +  > SIAM J. Discrete Math., 2006, to appear
 +  ** ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'':\\  An abstract simplicial complex represented by its facets.
 +  ** ''[[.:topaz:Visual_SimplicialComplex |Visual::SimplicialComplex]]'':\\  Visualization of the simplicial complex.
 +  ** ''[[.:topaz:Visual_SimplicialComplexLattice |Visual::SimplicialComplexLattice]]'':\\  Visualization of the ''[[.:topaz:SimplicialComplex#HASSE_DIAGRAM |HASSE_DIAGRAM]]'' of a simplicial complex as a multi-layer graph.
 +
 +===== Functions =====
 +
 +==== Comparing ====
 + These functions compare two ''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +----
 +{{anchor:find_facet_vertex_permutations:}}
 +  ?  **''find_facet_vertex_permutations([[.:topaz:SimplicialComplex |SimplicialComplex]] complex1, [[.:topaz:SimplicialComplex |SimplicialComplex]] complex2)''**
 +  :: Find the permutations of facets and vertices which maps the first complex to the second one. The facet permutation is the first component of the return value.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex1''
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex2''
 +    ? Returns:
 +    :''[[.:common#Pair |Pair]]<[[.:common#Array |Array]]<[[.:common#Int |Int]]>,[[.:common#Array |Array]]<[[.:common#Int |Int]]%%>>%%''
 +    ? Example:
 +    :: In the example below, two complexes are isomorphic, and the output shows first the facet permutation and then the vertex permutation of the isomorphism.
 +    :: <code perl> > $s1 = new SimplicialComplex(FACETS => [[0, 1], [0, 2], [1, 2], [2, 3]]);
 + > $s2 = new SimplicialComplex(FACETS => [[0, 1], [0, 3], [1, 3], [2, 3]]);
 + > print find_facet_vertex_permutations($s1, $s2);
 + <0 1 2 3> <0 1 3 2>
 +</code>
 +
 +
 +----
 +{{anchor:isomorphic:}}
 +  ?  **''isomorphic([[.:topaz:SimplicialComplex |SimplicialComplex]] complex1, [[.:topaz:SimplicialComplex |SimplicialComplex]] complex2)''**
 +  :: Determine whether two given complexes are combinatorially isomorphic. The problem is reduced to graph isomorphism of the vertex-facet incidence graphs.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex1'': (or Polytope)
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex2'': (or Polytope)
 +    ? Returns:
 +    :''[[.:common#Bool |Bool]]''
 +    ? Example:
 +    :: A minimal example of two complexes with the same f-vector, which are not isomorphic:
 +    :: <code perl> > $s1 = new SimplicialComplex(FACETS=>[[0,1],[0,2],[0,3]]);
 + > $s2 = new SimplicialComplex(FACETS=>[[0,1],[1,2],[2,3]]);
 + > print isomorphic($s1,$s2);
 + false
 +</code>
 +    :: <code perl> > print isomorphic($s1,$s1);
 + true
 +</code>
 +
 +
 +----
 +{{anchor:pl_homeomorphic:}}
 +  ?  **''pl_homeomorphic([[.:topaz:SimplicialComplex |SimplicialComplex]] complex1, [[.:topaz:SimplicialComplex |SimplicialComplex]] complex2)''**
 +  :: Tries to determine whether two complexes are pl-homeomorphic by using  bistellar flips and a simulated annealing strategy. You may specify the maximal number of //rounds//, how often the system may //relax// before heating up and how much //heat// should be applied. The function stops computing, once the size of the triangulation has not decreased for //rounds// iterations. If the //abs// flag is set, the function stops after //rounds// iterations regardless of when the last improvement took place. Additionally, you may set the threshold //min_n_facets// for the number of facets when the simplification ought to stop. Default is d+2 in the ''[[.:topaz:SimplicialComplex#CLOSED_PSEUDO_MANIFOLD |CLOSED_PSEUDO_MANIFOLD]]'' case and 1 otherwise. If you want to influence the distribution of the dimension of the moves when warming up you may do so by specifying a //distribution//. The number of values in //distribution// determines the dimensions used for heating up. The heating and relaxing parameters decrease dynamically unless the //constant// flag is set. The function prohibits to execute the reversed move of a move directly after the move itself unless the //allow_rev_move// flag is set. Setting the //allow_rev_move// flag might help solve a particular resilient problem. If you are interested in how the process is coming along, try the //verbose// option. It specifies after how many rounds the current best result is displayed. The //obj// determines the objective function used for the optimization. If //obj// is set to 0, the function searches for the triangulation with the lexicographically smallest f-vector, if //obj// is set to 1, the function searches for the triangulation with the reversed-lexicographically smallest f-vector and if //obj// is set to 2 the sum of the f-vector entries is used. The default is 1.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex1''
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex2''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''rounds''
 +    :: ''[[.:common#Bool |Bool]]'' ''abs''
 +    :: ''[[.:common#Int |Int]]'' ''obj''
 +    :: ''[[.:common#Int |Int]]'' ''relax''
 +    :: ''[[.:common#Int |Int]]'' ''heat''
 +    :: ''[[.:common#Bool |Bool]]'' ''constant''
 +    :: ''[[.:common#Bool |Bool]]'' ''allow_rev_move''
 +    :: ''[[.:common#Int |Int]]'' ''min_n_facets''
 +    :: ''[[.:common#Int |Int]]'' ''verbose''
 +    :: ''[[.:common#Int |Int]]'' ''seed''
 +    :: ''[[.:common#Bool |Bool]]'' ''quiet''
 +    :: ''[[.:common#Array |Array]]<[[.:common#Int |Int]]>'' ''distribution''
 +    ? Returns:
 +    :''[[.:common#Bool |Bool]]''
 +
 +
 +----
 +
 +==== Producing a new simplicial complex from others ====
 + These functions construct a new ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' from other objects of the same type.
 +----
 +{{anchor:alexander_dual:}}
 +  ?  **''alexander_dual([[.:topaz:SimplicialComplex |SimplicialComplex]] complex)''**
 +  :: Computes the Alexander dual complex, that is, the complements of all non-faces. The vertex labels are preserved unless the //no_labels// flag is specified.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The following creates the alexander dual of a particular graph on 5 vertices.
 +    :: <code perl> > $s = new SimplicialComplex(INPUT_FACES=>[[0, 1], [1, 2], [0, 2], [0, 3], [4]]);
 + > $t = alexander_dual($s);
 + > print $t -> F_VECTOR;
 + 5 10 6
 +</code>
 +
 +
 +----
 +{{anchor:barycentric_subdivision:}}
 +  ?  **''barycentric_subdivision([[.:topaz:SimplicialComplex |SimplicialComplex]] complex)''**
 +  :: Computes the __barycentric subdivision__ of //complex//.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#String |String]]'' ''pin_hasse_section'': default: HASSE_DIAGRAM
 +    :: ''[[.:common#String |String]]'' ''label_section'': default: VERTEX_LABELS
 +    :: ''[[.:common#String |String]]'' ''coord_section'': default: VERTICES
 +    :: ''[[.:common#Bool |Bool]]'' ''geometric_realization'': set to 1 to obtain a ''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]'', default: 0
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: To subdivide a triangle into six new triangles, do this:
 +    :: <code perl> > $b = barycentric_subdivision(simplex(2));
 +</code>
 +
 +
 +----
 +{{anchor:bistellar_simplification:}}
 +  ?  **''bistellar_simplification([[.:topaz:SimplicialComplex |SimplicialComplex]] complex)''**
 +  ::  Heuristic for simplifying the triangulation of the given manifold  without changing its PL-type. The function uses  bistellar flips and a simulated annealing strategy. You may specify the maximal number of //rounds//, how often the system may //relax// before heating up and how much //heat// should be applied. The function stops computing, once the size of the triangulation has not decreased for //rounds// iterations. If the //abs// flag is set, the function stops after //rounds// iterations regardless of when the last improvement took place. Additionally, you may set the threshold //min_n_facets// for the number of facets when the simplification ought to stop. Default is d+2 in the ''[[.:topaz:SimplicialComplex#CLOSED_PSEUDO_MANIFOLD |CLOSED_PSEUDO_MANIFOLD]]'' case and 1 otherwise. If you want to influence the distribution of the dimension of the moves when warming up you may do so by specifying a //distribution//. The number of values in //distribution// determines the dimensions used for heating up. The heating and relaxing parameters decrease dynamically unless the //constant// flag is set. The function prohibits to execute the reversed move of a move directly after the move itself unless the //allow_rev_move// flag is set. Setting the //allow_rev_move// flag might help solve a particular resilient problem. If you are interested in how the process is coming along, try the //verbose// option. It specifies after how many rounds the current best result is displayed. The //obj// determines the objective function used for the optimization. If //obj// is set to 0, the function searches for the triangulation with the lexicographically smallest f-vector, if //obj// is set to any other value the sum of the f-vector entries is used. The default is 1.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''rounds''
 +    :: ''[[.:common#Bool |Bool]]'' ''abs''
 +    :: ''[[.:common#Int |Int]]'' ''obj''
 +    :: ''[[.:common#Int |Int]]'' ''relax''
 +    :: ''[[.:common#Int |Int]]'' ''heat''
 +    :: ''[[.:common#Bool |Bool]]'' ''constant''
 +    :: ''[[.:common#Bool |Bool]]'' ''allow_rev_move''
 +    :: ''[[.:common#Int |Int]]'' ''min_n_facets''
 +    :: ''[[.:common#Int |Int]]'' ''verbose''
 +    :: ''[[.:common#Int |Int]]'' ''seed''
 +    :: ''[[.:common#Bool |Bool]]'' ''quiet''
 +    :: ''[[.:common#Array |Array]]<[[.:common#Int |Int]]>'' ''distribution''
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The following example applies bistellar simplification to the second barycentric subdivision of the boundary of the 4-simplex to recover the boundary of the 4-simplex itself.
 +    :: <code perl> > $s = iterated_barycentric_subdivision(simplex(4) -> BOUNDARY, 2);
 + > print bistellar_simplification($s) -> F_VECTOR;
 + 5 10 10 5
 +</code>
 +
 +
 +----
 +{{anchor:bs2quotient_by_equivalence:}}
 +  ?  **''bs2quotient_by_equivalence([[.:polytope:Polytope |Polytope]] P)''**
 +  :: Create a simplicial complex from a given complex by identifying vertices on the boundary of the second barycentric subdivision of the original complex according to some equivalence relation on faces.
 +    ? Parameters:
 +    :: ''[[.:polytope:Polytope |Polytope]]'' ''P'': the underlying polytope
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +  ?  **''bs2quotient_by_equivalence([[.:polytope:Polytope |Polytope]] P, [[.:topaz:SimplicialComplex |SimplicialComplex]] complex)''**
 +  :: Create a simplicial complex from a simplicial subdivision of a given complex by identifying vertices on the boundary of the original complex according to some equivalence relation on faces.
 +    ? Parameters:
 +    :: ''[[.:polytope:Polytope |Polytope]]'' ''P'': the underlying polytope
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex'': a sufficiently fine subdivision of P, for example the second barycentric subdivision
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +
 +
 +----
 +{{anchor:bs2quotient_by_group:}}
 +  ?  **''bs2quotient_by_group([[.:polytope:Polytope |Polytope]] P)''**
 +  :: Create a simplicial complex from a simplicial subdivision of a given complex by identifying vertices on the boundary of the second barycentric subdivision of the original complex according to a group that acts on vertices.
 +    ? Parameters:
 +    :: ''[[.:polytope:Polytope |Polytope]]'' ''P'': the underlying polytope
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +
 +
 +----
 +{{anchor:colored_ball_from_colored_sphere:}}
 +  ?  **''colored_ball_from_colored_sphere([[.:topaz:SimplicialComplex |SimplicialComplex]] complex)''**
 +  :: Extends the triangulation and coloring of a k-colored (d-1)-sphere to a max{k,d+1}-colored triangulation of a d-ball.  The colors are integer numbers.  The old vertex labels are preserved unless the //no_labels// flag is specified.  The new vertices get labeled ''new_i'' (i=0, 1, 2, ...). If a new label is not unique,  ''_j'' is added for the smallest integer j which makes the label unique.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_lables''
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? from extension:
 +    : [[:external_software|bundled:local]]
 +
 +
 +----
 +{{anchor:cone:}}
 +  ?  **''cone([[.:topaz:SimplicialComplex |SimplicialComplex]] complex, [[.:common#Int |Int]] k)''**
 +  :: Produce the //k//-cone over a given simplicial complex.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    :: ''[[.:common#Int |Int]]'' ''k'': default is 1
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Array |Array]]<[[.:common#String |String]]>'' ''apex_labels'': labels of the apex vertices.  Default labels have the form ''apex_0, apex_1, ...'' In the case the input complex has already vertex labels of this kind,  the duplicates are avoided.
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The following creates the cone with two apices over the triangle, with custom apex labels. The resulting complex is the 4-simplex.
 +    :: <code perl> > $c = cone(simplex(2),2,apex_labels=>['foo','bar']);
 + > print $c->FACETS;
 + {0 1 2 3 4}
 +</code>
 +    :: <code perl> > print $c->VERTEX_LABELS;
 + 0 1 2 foo bar
 +</code>
 +
 +
 +----
 +{{anchor:connected_sum:}}
 +  ?  **''connected_sum([[.:topaz:SimplicialComplex |SimplicialComplex]] complex1, [[.:topaz:SimplicialComplex |SimplicialComplex]] complex2, [[.:common#Int |Int]] f1, [[.:common#Int |Int]] f2)''**
 +  :: Compute the __connected sum__ of two complexes. Parameters //f_1// and //f_2// specify which facet of the first and second complex correspondingly are glued together. Default is the 0-th facet of both. The vertices in the selected facets are identified with each other according to their order in the facet (that is, in icreasing index order). The glueing facet iteself is not included in the connected sum.  The option //permutation// allows one to get an alternative identification. It should specify a permutation of the vertices of the second facet. The vertices of the new complex get the original labels with ''_1'' or ''_2'' appended, according to the input complex  they came from.  If you set the //no_labels// flag, the label generation will be omitted.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex1''
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex2''
 +    :: ''[[.:common#Int |Int]]'' ''f1'': default: 0
 +    :: ''[[.:common#Int |Int]]'' ''f2'': default: 0
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Array |Array]]<[[.:common#Int |Int]]>'' ''permutation''
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels''
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: Glueing together two tori to make a genus 2 double torus, rotating the second one clockwise:
 +    :: <code perl> > $cs = connected_sum(torus(),torus(),permutation=>[1,2,0]);
 + > print $cs->SURFACE.','.$cs->GENUS;
 + 1,2
 +</code>
 +
 +
 +----
 +{{anchor:deletion:}}
 +  ?  **''deletion([[.:topaz:SimplicialComplex |SimplicialComplex]] complex, [[.:common#Set |Set]]<[[.:common#Int |Int]]> face)''**
 +  :: Remove the given //face// and all the faces containing it.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    :: ''[[.:common#Set |Set]]<[[.:common#Int |Int]]>'' ''face'': specified by vertex indices.  Please use ''[[.:topaz:SimplicialComplex#labeled_vertices |labeled_vertices]]'' if you want to specify the face by vertex labels.
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: Deleting any face of the 3-simplex yields a pure 2-dimensional complex with 3 facets:
 +    :: <code perl> > $s = deletion(simplex(3),[0,1,2]);
 + > print $s->PURE, ', ', $s->DIM, ', ', $s->N_FACETS;
 + true, 2, 3
 +</code>
 +
 +
 +----
 +{{anchor:disjoint_union:}}
 +  ?  **''disjoint_union([[.:topaz:SimplicialComplex |SimplicialComplex]] complex1, [[.:topaz:SimplicialComplex |SimplicialComplex]] complex2)''**
 +  :: Produce the __disjoint union__ of the two given complexes.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex1''
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex2''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0 The vertex labels are built from the original labels with a suffix ''_1'' or ''_2'' appended.
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The following creates the disjoint union of a triangle and an edge.
 +    :: <code perl> > $s = disjoint_union(simplex(2), simplex(1));
 + > print $s -> F_VECTOR;
 + 5 4 1
 +</code>
 +
 +
 +----
 +{{anchor:edge_contraction:}}
 +  ?  **''edge_contraction([[.:topaz:SimplicialComplex |SimplicialComplex]] complex)''**
 +  :: Heuristic for simplifying the triangulation of the given manifold without changing its PL-type. Choosing a random order of the vertices, the function tries to contract all incident edges.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''seed''
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The following takes the second barycentric subdivision of the tetrahedron and performs edge contraction with a random order of the vertices. In the first instance the tetrahedron is recovered in the second it is not.
 +    :: <code perl> > $s = iterated_barycentric_subdivision(simplex(3) -> BOUNDARY, 2);
 + > $t = edge_contraction($s, seed=>100);
 + > $t1 = edge_contraction($s, seed => 101);
 + > print $t -> F_VECTOR;
 + 4 6 4
 +</code>
 +    :: <code perl> > print $t1 -> F_VECTOR;
 + 6 12 8
 +</code>
 +
 +
 +----
 +{{anchor:foldable_prism:}}
 +  ?  **''foldable_prism([[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]] complex)''**
 +  :: Produce a __prism__ over a given ''[[.:topaz:SimplicialComplex |SimplicialComplex]]''.
 +    ? Parameters:
 +    :: ''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]'' ''complex''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''geometric_realization''
 +    ? Returns:
 +    :''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]''
 +
 +
 +----
 +{{anchor:h_induced_quotient:}}
 +  ?  **''h_induced_quotient([[.:topaz:SimplicialComplex |SimplicialComplex]] C, [[.:common#Set |Set]]<[[.:common#Int |Int]]> vertices)''**
 +  :: Let //C// be the given simplicial and //A// the subcomplex induced by the given //vertices//. Then this function produces a simplicial complex homotopy equivalent to C mod A by adding the cone over A with apex a to C. The label of the apex my be specified via the option //apex//.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''C''
 +    :: ''[[.:common#Set |Set]]<[[.:common#Int |Int]]>'' ''vertices''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    :: ''[[.:common#String |String]]'' ''apex''
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The following takes C to be the suspension over a triangle and A to be the set of vertices of that triangle. The quotient induced is homotopy equivalent to a wedge of spheres.
 +    :: <code perl> > $C = suspension(simplex(2) -> BOUNDARY);
 + > $t = h_induced_quotient($C, [0, 1, 2]);
 + > print $t -> HOMOLOGY;
 + ({} 0)
 + ({} 0)
 + ({} 2)
 +</code>
 +
 +
 +----
 +{{anchor:induced_subcomplex:}}
 +  ?  **''induced_subcomplex([[.:topaz:SimplicialComplex |SimplicialComplex]] complex, [[.:common#Set |Set]]<[[.:common#Int |Int]]> vertices)''**
 +  :: Produce the subcomplex consisting of all faces which are contained in the given set of //vertices//.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    :: ''[[.:common#Set |Set]]<[[.:common#Int |Int]]>'' ''vertices''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    :: ''[[.:common#Bool |Bool]]'' ''geom_real'': tells the client to inherit the ''[[.:topaz:GeometricSimplicialComplex#COORDINATES |COORDINATES]]''.
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The following takes C to be the suspension over a triangle and the vertices to be the vertices of that triangle.
 +    :: <code perl> > $C = suspension(simplex(2) -> BOUNDARY);
 + > $t = induced_subcomplex($C, [0, 1, 2]);
 + > print $t -> F_VECTOR;
 + 3 3
 +</code>
 +
 +
 +----
 +{{anchor:iterated_barycentric_subdivision:}}
 +  ?  **''iterated_barycentric_subdivision([[.:topaz:SimplicialComplex |SimplicialComplex]] complex, [[.:common#Int |Int]] k)''**
 +  :: Computes the //k//-th __barycentric subdivision__ of //complex// by iteratively calling ''[[.:topaz#barycentric_subdivision |barycentric_subdivision]]''.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    :: ''[[.:common#Int |Int]]'' ''k''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#String |String]]'' ''pin_hasse_section'': default: HASSE_DIAGRAM
 +    :: ''[[.:common#String |String]]'' ''label_section'': default: VERTEX_LABELS
 +    :: ''[[.:common#String |String]]'' ''coord_section'': default: VERTICES
 +    :: ''[[.:common#Bool |Bool]]'' ''geometric_realization'': set to 1 to obtain a ''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]'', default: 0
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The following applies barycentric subdivision to the triangle twice.
 +    :: <code perl> > $b = iterated_barycentric_subdivision(simplex(2), 2);
 + > print $b -> F_VECTOR;
 + 25 60 36
 +</code>
 +
 +
 +----
 +{{anchor:join_complexes:}}
 +  ?  **''join_complexes([[.:topaz:SimplicialComplex |SimplicialComplex]] complex1, [[.:topaz:SimplicialComplex |SimplicialComplex]] complex2)''**
 +  :: Creates the join of //complex1// and //complex2//.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex1''
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex2''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0  The vertex labels are built from the original labels with a suffix ''_1'' or ''_2'' appended.
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The following constructs the tetrahedron as the join of two edges.
 +    :: <code perl> > $s = join_complexes(simplex(1), simplex(1));
 + > print $s -> F_VECTOR;
 + 4 6 4 1
 +</code>
 +
 +
 +----
 +{{anchor:k_skeleton:}}
 +  ?  **''k_skeleton([[.:topaz:SimplicialComplex |SimplicialComplex]] complex, [[.:common#Int |Int]] k)''**
 +  :: Produce the //k//-skeleton.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    :: ''[[.:common#Int |Int]]'' ''k''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The 2-skeleton of the 3-simplex is its boundary, a 2-sphere:
 +    :: <code perl> > print isomorphic(k_skeleton(simplex(3),2), simplex(3)->BOUNDARY);
 + true
 +</code>
 +  ?  **''k_skeleton([[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]] complex, [[.:common#Int |Int]] k)''**
 +  :: Produce the //k//-skeleton.
 +    ? Parameters:
 +    :: ''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]'' ''complex''
 +    :: ''[[.:common#Int |Int]]'' ''k''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    ? Returns:
 +    :''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]''
 +    ? Example:
 +    :: The 2-skeleton of the 3-ball is its boundary, a 2-sphere:
 +    :: <code perl> > print isomorphic(k_skeleton(ball(3),2), ball(3)->BOUNDARY);
 + true
 +</code>
 +
 +
 +----
 +{{anchor:link_subcomplex:}}
 +  ?  **''link_subcomplex([[.:topaz:SimplicialComplex |SimplicialComplex]] complex, [[.:common#Set |Set]]<[[.:common#Int |Int]]> face)''**
 +  :: Produce the __link__ of a //face// of the //complex//
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    :: ''[[.:common#Set |Set]]<[[.:common#Int |Int]]>'' ''face''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The following returns the 4-cycle obtained as the link of vertex 0 in the suspension over the triangle.
 +    :: <code perl> > $s = suspension(simplex(2)->BOUNDARY);
 + > $t = link_subcomplex($s, [0]);
 + > print $t->F_VECTOR;
 + 4 4
 +</code>
 +    ::  ''[[.:topaz:SimplicialComplex#VERTEX_INDICES |VERTEX_INDICES]]'' keep track of the embedding:
 +    :: <code perl> > $K = new SimplicialComplex(FACETS=>[[0,1,2,3],[1,2,3,4]]);
 + > $lk_12 = link_subcomplex($K,[1,2]);
 + > print $lk_12->FACETS->[0];
 + {0 1}
 +</code>
 +    :: <code perl> > $idx = $lk_12->VERTEX_INDICES;
 + > map { print $idx->[$_], ' ' } @{$lk_12->FACETS->[0]};
 + 0 3
 +</code>
 +
 +
 +----
 +{{anchor:simplicial_product:}}
 +  ?  **''simplicial_product([[.:topaz:SimplicialComplex |SimplicialComplex]] complex1, [[.:topaz:SimplicialComplex |SimplicialComplex]] complex2)''**
 +  :: Computes the __simplicial product__ of two complexes. Vertex orderings may be given as options.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex1''
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex2''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Array |Array]]<[[.:common#Int |Int]]>'' ''vertex_order1''
 +    :: ''[[.:common#Array |Array]]<[[.:common#Int |Int]]>'' ''vertex_order2''
 +    :: ''[[.:common#Bool |Bool]]'' ''geometric_realization'': default 0
 +    :: ''[[.:common#Bool |Bool]]'' ''color_cons''
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The following returns the product of two edges.
 +    :: <code perl> > $s = simplicial_product(simplex(1), simplex(1));
 + > print $s -> F_VECTOR;
 + 4 5 2
 +</code>
 +  ?  **''simplicial_product<Scalar>([[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]] complex1, [[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]] complex2)''**
 +  :: Computes the __simplicial product__ of two complexes. Vertex orderings may be given as options.
 +    ? Type Parameters:
 +    :: ''Scalar''
 +    ? Parameters:
 +    :: ''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]'' ''complex1''
 +    :: ''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]'' ''complex2''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Array |Array]]<[[.:common#Int |Int]]>'' ''vertex_order1''
 +    :: ''[[.:common#Array |Array]]<[[.:common#Int |Int]]>'' ''vertex_order2''
 +    :: ''[[.:common#Bool |Bool]]'' ''geometric_realization'': default 1
 +    :: ''[[.:common#Bool |Bool]]'' ''color_cons''
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    ? Returns:
 +    :''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]<Scalar>''
 +    ? Example:
 +    :: The following returns the product of the edges (0, 0)--(1, 0) and (0, 0) -- (2, 0).
 +    :: <code perl> > $C = new GeometricSimplicialComplex(COORDINATES => [[0, 0], [1, 0]], FACETS => [[0, 1]]);
 + > $C1 = new GeometricSimplicialComplex(COORDINATES => [[0, 2], [0, 0]], FACETS => [[0, 1]]);
 + > $s = simplicial_product($C, $C1);
 + > print $s -> COORDINATES;
 + 0 0 0 2
 + 1 0 0 2
 + 0 0 0 0
 + 1 0 0 0
 +</code>
 +
 +
 +----
 +{{anchor:star_deletion:}}
 +  ?  **''star_deletion([[.:topaz:SimplicialComplex |SimplicialComplex]] complex, [[.:common#Set |Set]]<[[.:common#Int |Int]]> face)''**
 +  :: Remove the star of a given //face//.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    :: ''[[.:common#Set |Set]]<[[.:common#Int |Int]]>'' ''face'': specified by vertex indices.  Please use ''[[.:topaz:SimplicialComplex#labeled_vertices |labeled_vertices]]'' if you want to specify the face by vertex labels.
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The following removes the star of the vertex 0 from the suspension over a triangle.
 +    :: <code perl> > $s = suspension(simplex(2) -> BOUNDARY);
 + > $t = star_deletion($s, [0]);
 + > print $t -> F_VECTOR;
 + 4 5 2
 +</code>
 +
 +
 +----
 +{{anchor:star_subcomplex:}}
 +  ?  **''star_subcomplex([[.:topaz:SimplicialComplex |SimplicialComplex]] complex, [[.:common#Set |Set]]<[[.:common#Int |Int]]> face)''**
 +  :: Produce the __star__ of the //face// of the //complex//.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    :: ''[[.:common#Set |Set]]<[[.:common#Int |Int]]>'' ''face''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The following returns the cone over the 4-cycle obtained as the star of vertex 0 in the suspension over the triangle.
 +    :: <code perl> > $s = suspension(simplex(2) -> BOUNDARY);
 + > $t = star_subcomplex($s, [0]);
 + > print $t -> F_VECTOR;
 + 5 8 4
 +</code>
 +
 +
 +----
 +{{anchor:stellar_subdivision:}}
 +  ?  **''stellar_subdivision([[.:topaz:SimplicialComplex |SimplicialComplex]] complex, [[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%% faces)''**
 +  :: Computes the complex obtained by stellar subdivision of the given //faces// of the //complex//.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    :: ''[[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%%'' ''faces''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    :: ''[[.:common#Bool |Bool]]'' ''geometric_realization'': default 0
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +  ?  **''stellar_subdivision([[.:topaz:SimplicialComplex |SimplicialComplex]] complex, [[.:common#Set |Set]]<[[.:common#Int |Int]]> face)''**
 +  :: Computes the complex obtained by stellar subdivision of the given //face// of the //complex//.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    :: ''[[.:common#Set |Set]]<[[.:common#Int |Int]]>'' ''face''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    :: ''[[.:common#Bool |Bool]]'' ''geometric_realization'': default 0
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +
 +
 +----
 +{{anchor:sum_triangulation:}}
 +  ?  **''sum_triangulation([[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]] P, [[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]] Q, [[.:common#IncidenceMatrix |IncidenceMatrix]] WebOfStars)''**
 +  :: Produce a specific sum-triangulation of two given triangulations. and a WebOfStars.  There are P-sum-triangulations and Q-sum-triangulations. If the image of the star of the origin of P is empty then we have a Q-sum-triangulation; otherwise it is a P-sum-triangulation. For details see Assarf, Joswig & Pfeifle: Webs of stars or how to triangulate sums of polytopes, to appear
 +    ? Parameters:
 +    :: ''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]'' ''P'': first complex
 +    :: ''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]'' ''Q'': second complex
 +    :: ''[[.:common#IncidenceMatrix |IncidenceMatrix]]'' ''WebOfStars'': Every row corresponds to a full dimensional simplex in P and every column to a full dimensional simplex in Q.
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''origin_first'': decides if the origin should be the first point in the resulting complex. Default=0
 +    ? Returns:
 +    :''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]''
 +
 +
 +----
 +{{anchor:suspension:}}
 +  ?  **''suspension([[.:topaz:SimplicialComplex |SimplicialComplex]] complex, [[.:common#Int |Int]] k)''**
 +  :: Produce the __//k//-suspension__ over a given simplicial complex.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    :: ''[[.:common#Int |Int]]'' ''k'': default value is 1
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Array |Array]]<[[.:common#String |String]]>'' ''labels'': for the apices.  By default apices are labeled with ''apex_0+'', ''apex_0-'', ''apex_1+'', etc.  If one of the specified labels already exists, a unique one is made  by appending ''_i'' where //i// is some small number.
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The suspension of a 1-sphere is a 2-sphere:
 +    :: <code perl> > $s = new SimplicialComplex(FACETS=>[[0,1],[1,2],[2,0]]);
 + > print suspension($s)->HOMOLOGY;
 + ({} 0)
 + ({} 0)
 + ({} 1)
 +</code>
 +
 +
 +----
 +{{anchor:triang_neighborhood:}}
 +  ?  **''triang_neighborhood([[.:topaz:SimplicialComplex |SimplicialComplex]] complex, [[.:common#Rational |Rational]] width)''**
 +  :: Create a triangulated tubular neighborhood of a  [[.:topaz:SimplicialComplex#PURE |pure]] 2-complex.  If the complex is a link  with the property that each vertex and its two neighbours are in general  position after projection to the x,y-plane, then one might specify  a rational number //width// to tell the client to compute ''[[.:topaz:GeometricSimplicialComplex#COORDINATES |COORDINATES]]''  of the triangulated tubular neighborhood. If the //width/// is  chosen too large, the computed realization will be self intersecting.  If each connected component of the link has an even number of facets,  then the following holds:  An edge of the resulting complex is contained in an odd number of  facets iff it corresponds to one of the edges of the link. 
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    :: ''[[.:common#Rational |Rational]]'' ''width'': default: 0
 +    ? from extension:
 +    : [[:external_software|bundled:local]]
 +
 +
 +----
 +{{anchor:union:}}
 +  ?  **''union([[.:topaz:SimplicialComplex |SimplicialComplex]] complex1, [[.:topaz:SimplicialComplex |SimplicialComplex]] complex2)''**
 +  :: Produce the union of the two given complexes, identifying vertices with equal labels.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex1''
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex2''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The union of two 3-simplices with the same labels on vertices produces the 3-simplex again.
 +    :: <code perl> > print union(simplex(3), simplex(3)) -> F_VECTOR;
 + 4 6 4 1
 +</code>
 +
 +
 +----
 +{{anchor:web_of_stars:}}
 +  ?  **''web_of_stars([[.:common#Array |Array]]<[[.:common#Int |Int]]> poset_hom, [[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%%> star_shaped_balls, [[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%% triang)''**
 +  :: Produce a web of stars from two given triangulations and a map between them.
 +    ? Parameters:
 +    :: ''[[.:common#Array |Array]]<[[.:common#Int |Int]]>'' ''poset_hom'': the poset homomorphism from stabbing order to star-shaped balls
 +    :: ''[[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%%>'' ''star_shaped_balls'': the collection of star-shaped balls of T
 +    :: ''[[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%%'' ''triang'': the facets of the underlying triangulation of Q
 +    ? Returns:
 +    :''[[.:common#IncidenceMatrix |IncidenceMatrix]]''
 +
 +
 +----
 +
 +==== Producing a simplicial complex from other objects ====
 + These functions construct a new ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' from other objects.
 +----
 +{{anchor:broken_circuit_complex:}}
 +  ?  **''broken_circuit_complex([[.:matroid:Matroid |Matroid]] M, [[.:common#Array |Array]]<[[.:common#Int |Int]]> O)''**
 +  :: Compute the broken circuit complex of a matroid. Given an ordering on the ground set of the matroid, a broken circuit is simply C{c}, where C is a circuit and c its maximal element under this ordering. The broken circuit complex of a matroid is then the abstract simplicial complex generated by those subsets of its ground set, which do not contain a broken circuit. Every such set must be a basis of the matroid.
 +    ? Parameters:
 +    :: ''[[.:matroid:Matroid |Matroid]]'' ''M'': the input matroid
 +    :: ''[[.:common#Array |Array]]<[[.:common#Int |Int]]>'' ''O'': representing an ordering function on the base set of M (its semantics are that i > j iff O[i]>O[j])
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: A matroid with 3 bases {0,1}, {0,2}, and {1,2}. The only circuit is {0,1,2}, hence the only broken circuit (with the standard ordering) is {0,1}.
 +    :: <code perl> > $m = new matroid::Matroid(VECTORS=>[[1,0],[0,1],[1,1]]);
 + > print broken_circuit_complex($m)->FACETS;
 + {0 2}
 + {1 2}
 +</code>
 +    ? Example:
 +    :: The same matroid, but with a different ordering on its ground set.
 +    :: <code perl> > $m = new matroid::Matroid(VECTORS=>[[1,0],[0,1],[1,1]]);
 + > $ord = new Array<Int>(0,2,1);
 + > print broken_circuit_complex($m, $ord)->FACETS;
 + {0 1}
 + {1 2}
 +</code>
 +
 +
 +----
 +{{anchor:clique_complex:}}
 +  ?  **''clique_complex([[.:graph:Graph |Graph]] graph)''**
 +  :: Produce the __clique complex__ of a given graph, that is, the simplicial complex that has an n-dimensional facet for each n+1-clique. If //no_labels// is set to 1, the labels are not copied.
 +    ? Parameters:
 +    :: ''[[.:graph:Graph |Graph]]'' ''graph''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: Create the clique complex of a simple graph with one 3-clique and  one 2-clique, not creating labels.
 +    :: <code perl> > $g = graph_from_edges([[0,1],[0,2],[1,2],[2,3]]);
 + > $c = clique_complex($g,no_labels=>1);
 + > print $c->FACETS;
 + {0 1 2}
 + {2 3}
 +</code>
 +
 +
 +----
 +{{anchor:independence_complex:}}
 +  ?  **''independence_complex([[.:matroid:Matroid |Matroid]] matroid)''**
 +  :: Produce the __independence complex__ of a given matroid. If //no_labels// is set to 1, the labels are not copied.
 +    ? Parameters:
 +    :: ''[[.:matroid:Matroid |Matroid]]'' ''matroid''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''no_labels'': Do not create ''[[.:topaz:SimplicialComplex#VERTEX_LABELS |VERTEX_LABELS]]''. default: 0
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The following example constructs the independence complex from a rank 3 matroid on 4 elements.
 +    :: <code perl> > $M = new matroid::Matroid(VECTORS=>[[1, 0, 0], [1, 0, 1], [1, 1, 0], [1, 0, 2]]);
 + > print independence_complex($M) -> F_VECTOR;
 + 4 6 3
 +</code>
 +
 +
 +----
 +{{anchor:vietoris_rips_complex:}}
 +  ?  **''vietoris_rips_complex([[.:common#Matrix |Matrix]] D, [[.:common#Rational |Rational]] delta)''**
 +  :: Computes the __Vietoris Rips complex__ of a point set. The set is passed as its so-called "distance matrix", whose (i,j)-entry is the distance between point i and j. This matrix can e.g. be computed using the distance_matrix function. The points corresponding to vertices of a common simplex will all have a distance less than //delta// from each other.
 +    ? Parameters:
 +    :: ''[[.:common#Matrix |Matrix]]'' ''D'': the "distance matrix" of the point set (can be upper triangular)
 +    :: ''[[.:common#Rational |Rational]]'' ''delta''
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The VR-complex from 3 points (vertices of a triangle with side lengths 3, 3, and 5) for different delta:
 +    :: <code perl> > print vietoris_rips_complex(new Matrix([[0,3,3],[0,0,5],[0,0,0]]), 2)->FACETS;
 + {0}
 + {1}
 + {2}
 +</code>
 +    :: <code perl> > print vietoris_rips_complex(new Matrix([[0,3,3],[0,0,5],[0,0,0]]), 4)->FACETS;
 + {0 1}
 + {0 2}
 +</code>
 +    :: <code perl> > print vietoris_rips_complex(new Matrix([[0,3,3],[0,0,5],[0,0,0]]), 6)->FACETS;
 + {0 1 2}
 +</code>
 +
 +
 +----
 +
 +==== Producing from scratch ====
 + With these clients you can create special examples of simplicial complexes and complexes belonging to parameterized families.
 +----
 +{{anchor:ball:}}
 +  ?  **''ball([[.:common#Int |Int]] d)''**
 +  :: A //d//-dimensional __ball__, realized as the //d//-simplex.
 +    ? Parameters:
 +    :: ''[[.:common#Int |Int]]'' ''d'': dimension
 +    ? Returns:
 +    :''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]''
 +    ? Example:
 +    :: The following produces the 3-ball and stores it in the variable $b:
 +    :: <code perl> > $b = ball(3);
 +</code>
 +    ::  You can print the facets of the resulting simplicial complex like so:
 +    :: <code perl> > print $b->FACETS;
 + {0 1 2 3}
 +</code>
 +
 +
 +----
 +{{anchor:bipyramidal_3_sphere:}}
 +  ?  **''bipyramidal_3_sphere([[.:common#Int |Int]] n)''**
 +  :: Create the 3-sphere with bipyramidal and tetrahedral facets from [Nevo, Santos & Wilson, Many triangulated odd-dimensional spheres, Math Ann 364 (2016), 737-762
 +    ? Parameters:
 +    :: ''[[.:common#Int |Int]]'' ''n'': an integer >= 3
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''verbosity'': default 0
 +    ? Returns:
 +    :''[[.:fan:PolyhedralComplex |PolyhedralComplex]]<[[.:common#Rational |Rational]]>''
 +
 +
 +----
 +{{anchor:bistellar_d_sphere:}}
 +  ?  **''bistellar_d_sphere([[.:common#Int |Int]] D, [[.:common#Int |Int]] n)''**
 +  :: Create a (D = 2d-1)-sphere made from d paths of n vertices from [Nevo, Santos & Wilson, Many triangulated odd-dimensional spheres, Math Ann 364 (2016), 737-762.
 +    ? Parameters:
 +    :: ''[[.:common#Int |Int]]'' ''D'': the dimension of the sphere, an integer >= 2
 +    :: ''[[.:common#Int |Int]]'' ''n'': the number of vertices along a path, an integer >= 3
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''verbosity'': default 0
 +    :: ''[[.:common#Int |Int]]'' ''i'': the serial number of which triangulation to choose,  where 0 <= i <= min(2^k_max - 1, 2^32 - 1), k_max = floor(d(n-1)/(d+2)), and d=(D+1)/2 the number of paths. The value of i will be clamped to that range; default is 0
 +    :: ''[[.:common#Bool |Bool]]'' ''check_constructibility'': default 0: check that the sphere is constructible according to the lemmata in Yirong Yang, https://arxiv.org/abs/2305.03186. The proof in that paper currently has an error whenever d+2 divides d(n-1), e.g. for (D,d,n) = (5,3,11), (7,4,10).
 +    :: ''[[.:common#Bool |Bool]]'' ''output_on_error'': default 1 output instances of the failed shellings in those cases
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +
 +
 +----
 +{{anchor:complex_projective_plane:}}
 +  ?  **''complex_projective_plane()''**
 +  :: The complex projective plane with the vertex-minimal triangulation by Kühnel and Brehm.
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: Construct the complex projective plane, store it in the variable $p2c, and print its homology group.
 +    :: <code perl> > $p2c = complex_projective_plane();
 + > print $p2c->HOMOLOGY;
 + ({} 0)
 + ({} 0)
 + ({} 1)
 + ({} 0)
 + ({} 1)
 +</code>
 +
 +
 +----
 +{{anchor:cube_complex:}}
 +  ?  **''cube_complex([[.:common#Array |Array]]<[[.:common#Int |Int]]> x)''**
 +  :: Produces a triangulated pile of hypercubes, arranged in a d-dimensional array. Each cube is split into d! tetrahedra, and the tetrahedra are all grouped around one of the diagonal axes of the cube.
 +    ? Parameters:
 +    :: ''[[.:common#Array |Array]]<[[.:common#Int |Int]]>'' ''x'': specifies the shape of the pile: d=x.size is the dimension of the cubes to be stacked, and the stack will be x_1 by x_2 by ... by x_d cubes.
 +    ? Returns:
 +    :''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]<[[.:common#Rational |Rational]]>''
 +    ? Example:
 +    :: Arrange four triangulated 3-cubes to form a big 2 by 2 cube:
 +    :: <code perl> > $cc = cube_complex([2,2,2]);
 + > print $cc->description;
 + 2x2x2 Pile of 3-dimensional triangulated cubes.
 +</code>
 +
 +
 +----
 +{{anchor:jockusch_3_ball:}}
 +  ?  **''jockusch_3_ball([[.:common#Int |Int]] n)''**
 +  :: Create the ball B^{3,1}_n contained in Jockusch's centrally symmetric 3-sphere Delta^3_n on 2n vertices see Lemma 3.1 in arxiv.org/abs/2005.01155
 +    ? Parameters:
 +    :: ''[[.:common#Int |Int]]'' ''n'': an integer >= 4
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''label_style'': : 0(default) with dashes; 1 with bars
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +
 +
 +----
 +{{anchor:jockusch_3_sphere:}}
 +  ?  **''jockusch_3_sphere([[.:common#Int |Int]] n)''**
 +  :: Create Jockusch's centrally symmetric 3-sphere Delta^3_n on 2n vertices see Lemma 3.1 in arxiv.org/abs/2005.01155
 +    ? Parameters:
 +    :: ''[[.:common#Int |Int]]'' ''n'': an integer >= 4
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''label_style'': : 0(default) with dashes; 1 with bars
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +
 +
 +----
 +{{anchor:klein_bottle:}}
 +  ?  **''klein_bottle()''**
 +  :: The Klein bottle.
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +
 +
 +----
 +{{anchor:multi_associahedron_sphere:}}
 +  ?  **''multi_associahedron_sphere([[.:common#Int |Int]] n, [[.:common#Int |Int]] k)''**
 +  :: Produce the simplicial sphere //Δ(n,k)// of (//k//+1)-crossing free multitriangulations of an //n//-gon //P//, along with the group action on the diagonals induced from //D//_{2//n//}. //Δ(n,k)// is the simplicial complex on the set of relevant diagonals of //P// whose faces are those sets of diagonals such that no //k//+1 of them mutually cross. A diagonal is //relevant// if it leaves //k// or more vertices of //P// on both sides. (Any diagonal having less than //k// vertices on one side trivially cannot participate in a (//k//+1)-crossing, so is //irrelevant//. The corresponding complex on //all// diagonals is therefore the simplicial join of this one with the simplex of irrelevant diagonals.)
 +  > Jakob Jonsson, "Generalized triangulations and diagonal-free subsets of stack polyominoes",
 +  > J. Combin. Theory Ser. A, 112(1):117–142, 2005
 +  .. //Δ(n,k)// is known to be a //k//-neighborly vertex-decomposable sphere of dimension //k//ν-1, where the parameter ν=//n//-2//k//-1 measures the complexity of this construction. For ν=0, the complex is a point; for ν=1 a //k//-simplex; for ν=2 the boundary of a cyclic polytope. Setting //k//=1 yields the boundary of the simplicial associahedron. The list of (//k//+1)-crossings in the //n//-gon is included as the attachment K_PLUS_1_CROSSINGS. It can also be obtained as the property MINIMAL_NON_FACES, but this requires the HASSE_DIAGRAM to be computed.
 +    ? Parameters:
 +    :: ''[[.:common#Int |Int]]'' ''n'': the number of vertices of the polygon
 +    :: ''[[.:common#Int |Int]]'' ''k'': the number of diagonals that are allowed to mutually cross
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''include_facets'': calculate the facets (for large examples)? Default 1
 +    :: ''[[.:common#Bool |Bool]]'' ''include_crossings'': calculate the crossings? Default 1
 +    :: ''[[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%%'' ''link_of_diagonals'': calculate the link of the sphere of the given diagonals. This option implies include_crossings=>0 and causes no GROUP to be generated
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The f-vector of Δ(9,3) is that of a neighborly polytope, since ν=2:
 +    :: <code perl> > print multi_associahedron_sphere(9,3)->F_VECTOR;
 + 9 36 84 117 90 30
 +</code>
 +    ? Example:
 +    :: The option include_facets=>0 still leaves useful information:
 +    :: <code perl> > $s = multi_associahedron_sphere(8,2, include_facets=>0);
 + > print $s->VERTEX_LABELS;
 + (0 3) (1 4) (2 5) (3 6) (4 7) (0 5) (1 6) (2 7) (0 4) (1 5) (2 6) (3 7)
 +</code>
 +    :: <code perl> > print $s->GROUP->PERMUTATION_ACTION->GENERATORS;
 + 7 0 1 2 3 4 5 6 11 8 9 10
 + 4 3 2 1 0 7 6 5 11 10 9 8
 +</code>
 +    :: <code perl> > print $s->get_attachment("K_PLUS_1_CROSSINGS")->size();
 + 28
 +</code>
 +
 +
 +----
 +{{anchor:nz_4_ball:}}
 +  ?  **''nz_4_ball([[.:common#Int |Int]] n)''**
 +  :: Create the ball B^{4,1}_n contained in Novik & Zheng's centrally symmetric 4-sphere Delta^4_n on 2n vertices see arxiv.org/abs/2005.01155
 +    ? Parameters:
 +    :: ''[[.:common#Int |Int]]'' ''n'': an integer >= 5
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''label_style'': : 0(default) with dashes; 1 with bars
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +
 +
 +----
 +{{anchor:nz_4_sphere:}}
 +  ?  **''nz_4_sphere([[.:common#Int |Int]] n)''**
 +  :: Create Novik & Zheng's centrally symmetric 4-sphere Delta^4_n on 2n vertices see arxiv.org/abs/2005.01155
 +    ? Parameters:
 +    :: ''[[.:common#Int |Int]]'' ''n'': an integer >= 5
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''label_style'': : 0(default) with dashes; 1 with bars
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +
 +
 +----
 +{{anchor:poincare_sphere:}}
 +  ?  **''poincare_sphere()''**
 +  :: The 16-vertex triangulation of the Poincaré homology 3-sphere by Björner and Lutz, Experimental Mathematics, Vol. 9 (2000), No. 2.
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: Print the face numbers.
 +    :: <code perl> > print poincare_sphere()->F_VECTOR;
 + 16 106 180 90
 +</code>
 +
 +
 +----
 +{{anchor:rand_knot:}}
 +  ?  **''rand_knot([[.:common#Int |Int]] n_edges)''**
 +  :: Produce a random knot (or link) as a polygonal closed curve in 3-space. The knot (or each connected component of the link) has //n_edges// edges. The vertices are uniformly distributed in [-1,1]<sup>3</sup>, unless the //on_sphere// option is set. In the latter case the vertices are uniformly distributed on the 3-sphere. Alternatively the //brownian// option produces a knot by connecting the ends of a simulated brownian motion.
 +    ? Parameters:
 +    :: ''[[.:common#Int |Int]]'' ''n_edges''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''n_comp'': number of components, default is 1.
 +    :: ''[[.:common#Bool |Bool]]'' ''on_sphere''
 +    :: ''[[.:common#Bool |Bool]]'' ''brownian''
 +    :: ''[[.:common#Int |Int]]'' ''seed''
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +    ? Example:
 +    :: The following generates a random knot with 6 edges from 6 random points on the cube.
 +    :: <code perl> > $K = rand_knot(6);
 +</code>
 +
 +
 +----
 +{{anchor:real_projective_plane:}}
 +  ?  **''real_projective_plane()''**
 +  :: The real projective plane with its unique minimal triangulation on six vertices.
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +
 +
 +----
 +{{anchor:simplex:}}
 +  ?  **''simplex([[.:common#Int |Int]] d)''**
 +  :: A __simplex__ of dimension //d//.
 +    ? Parameters:
 +    :: ''[[.:common#Int |Int]]'' ''d'': dimension
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +
 +
 +----
 +{{anchor:sphere:}}
 +  ?  **''sphere([[.:common#Int |Int]] d)''**
 +  :: The //d//-dimensional __sphere__, realized as the boundary of the (//d//+1)-simplex.
 +    ? Parameters:
 +    :: ''[[.:common#Int |Int]]'' ''d'': dimension
 +    ? Returns:
 +    :''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]''
 +
 +
 +----
 +{{anchor:surface:}}
 +  ?  **''surface([[.:common#Int |Int]] g)''**
 +  :: Produce a __surface of genus //g//__. For //g// >= 0 the client produces an orientable surface, otherwise it produces a non-orientable one.
 +    ? Parameters:
 +    :: ''[[.:common#Int |Int]]'' ''g'': genus
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +
 +
 +----
 +{{anchor:torus:}}
 +  ?  **''torus()''**
 +  :: The Császár Torus. Geometric realization by Frank Lutz, Electronic Geometry Model No. 2001.02.069
 +    ? Returns:
 +    :''[[.:topaz:SimplicialComplex |SimplicialComplex]]''
 +
 +
 +----
 +{{anchor:unknot:}}
 +  ?  **''unknot([[.:common#Int |Int]] m, [[.:common#Int |Int]] n)''**
 +  :: Produces a triangulated 3-sphere with the particularly NASTY embedding of the unknot in its 1-skeleton. The parameters //m// >= 2 and //n// >= 1 determine how entangled the unknot is. //eps// determines the ''[[.:topaz:GeometricSimplicialComplex#COORDINATES |COORDINATES]]''.
 +    ? Parameters:
 +    :: ''[[.:common#Int |Int]]'' ''m''
 +    :: ''[[.:common#Int |Int]]'' ''n''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Rational |Rational]]'' ''eps''
 +    ? Returns:
 +    :''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]''
 +
 +
 +----
 +
 +==== Producing other objects ====
 + Functions producing big objects which are not contained in application topaz.
 +----
 +{{anchor:outitudes:}}
 +  ?  **''outitudes([[.:common#Matrix |Matrix]]<[[.:common#Int |Int]]> DCEL_data, [[.:common#Vector |Vector]]<[[.:common#Rational |Rational]]> A_coords)''**
 +  :: Computes the outitudes along edges.
 +    ? Parameters:
 +    :: ''[[.:common#Matrix |Matrix]]<[[.:common#Int |Int]]>'' ''DCEL_data''
 +    :: ''[[.:common#Vector |Vector]]<[[.:common#Rational |Rational]]>'' ''A_coords''
 +    ? Returns:
 +    :''[[.:common#Vector |Vector]]<[[.:common#Rational |Rational]]>''
 +    ? Example:
 +    :: In the following example only edge 2 has negative outitude.
 +    :: <code perl> > $T1 = new Matrix<Int>([[0,0,2,3,0,1],[0,0,4,5,0,1],[0,0,0,1,0,1]]);
 + > print outitudes($T1,[1,2,3,4,5,6,1,2]);
 + 37 37 -5
 +</code>
 +
 +
 +----
 +{{anchor:projective_potato:}}
 +  ?  **''projective_potato([[.:common#Matrix |Matrix]]<[[.:common#Int |Int]]> DCEL_data, [[.:common#Vector |Vector]]<[[.:common#Rational |Rational]]> A_coords, [[.:common#Matrix |Matrix]]<[[.:common#Rational |Rational]]> first_two_vertices, [[.:common#Int |Int]] depth)''**
 +  :: Computes the triangulated convex projective set that covers the convex RP^2 surface. The latter is given by the DCEL data for the triangulation of the surface along with A-coordinates (one positive Rational for each oriented edge and each triangle). Obviously, we only can compute a finite part of the infinite covering triangulation
 +    ? Parameters:
 +    :: ''[[.:common#Matrix |Matrix]]<[[.:common#Int |Int]]>'' ''DCEL_data''
 +    :: ''[[.:common#Vector |Vector]]<[[.:common#Rational |Rational]]>'' ''A_coords''
 +    :: ''[[.:common#Matrix |Matrix]]<[[.:common#Rational |Rational]]>'' ''first_two_vertices'': at the moment has to be the Matrix with rows (1,0,0),(0,1,0)
 +    :: ''[[.:common#Int |Int]]'' ''depth''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''lifted'': for producing the lifted triangulation in R^3 with vertices in the light cone
 +    ? Returns:
 +    :''[[.:fan:PolyhedralComplex |PolyhedralComplex]]<[[.:common#Rational |Rational]]>''
 +    ? Example:
 +    :: The following computes a covering triangulation of a once punctured torus up to depth 5:
 +    :: <code perl> > $T1 = new Matrix<Int>([[0,0,2,3,0,1],[0,0,4,5,0,1],[0,0,0,1,0,1]]);
 + > $p = projective_potato($T1,new Vector([1,1,1,1,1,1,2,2]),new Matrix([[1,0,0],[0,1,0]]),1);
 + > print $p->VERTICES;
 + 1 1 0 0
 + 1 0 1 0
 + 1 0 0 1
 + 1 1 1 -1
 + 1 -1/5 2/5 4/5
 + 1 2/5 -1/5 4/5
 +</code>
 +
 +
 +----
 +{{anchor:secondary_polyhedron:}}
 +  ?  **''secondary_polyhedron([[.:topaz:HyperbolicSurface |HyperbolicSurface]] s, [[.:common#Int |Int]] depth)''**
 +  :: Computes the secondary polyhedron of a hyperbolic surface up to a given depth of the spanning tree of the covering triangluation of the hypoerbolic plane.
 +    ? Parameters:
 +    :: ''[[.:topaz:HyperbolicSurface |HyperbolicSurface]]'' ''s''
 +    :: ''[[.:common#Int |Int]]'' ''depth''
 +    ? Returns:
 +    :''[[.:polytope:Polytope |Polytope]]<[[.:common#Float |Float]]>''
 +
 +
 +----
 +
 +==== Symmetry ====
 + These functions capture information of the object that is concerned with the action of permutation groups.
 +----
 +{{anchor:combinatorial_symmetries:}}
 +  ?  **''combinatorial_symmetries([[.:topaz:SimplicialComplex |SimplicialComplex]] sigma)''**
 +  :: Compute the combinatorial symmetries (i.e., automorphisms of the face lattice) of a given simplicial complex. They are stored in terms of a GROUP.RAYS_ACTION and a GROUP.FACETS_ACTION property, and the GROUP.RAYS_ACTION is also returned.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''sigma''
 +    ? Returns:
 +    :''[[.:group:PermutationAction |PermutationAction]]''
 +    ? Example:
 +    :: To get the vertex symmetry group of the square and print its generators, type the following:
 +    :: <code perl> > $sigma = new SimplicialComplex(FACETS=>[[0,1],[1,2],[2,3],[0,3]]);
 + > print combinatorial_symmetries($sigma)->GENERATORS;
 + 3 2 1 0
 + 0 3 2 1
 +</code>
 +    :: <code perl> > print $sigma->GROUP->RAYS_ACTION->GENERATORS;
 + 0 3 2 1
 + 1 0 3 2
 +</code>
 +    :: <code perl> > print $sigma->GROUP->FACETS_ACTION->GENERATORS;
 + 3 2 1 0
 + 0 3 2 1
 +</code>
 +
 +
 +----
 +
 +==== Topology ====
 + The following functions compute topological invariants.
 +----
 +{{anchor:betti_numbers:}}
 +  ?  **''betti_numbers<Coeff>([[.:topaz#ChainComplex |ChainComplex]] C)''**
 +  :: Calculate the betti numbers of a general chain complex over a field.
 +    ? Type Parameters:
 +    :: ''Coeff'': The coefficient field type for homology computation. Defaults to Rational
 +    ? Parameters:
 +    :: ''[[.:topaz#ChainComplex |ChainComplex]]'' ''C''
 +    ? Returns:
 +    :''[[.:common#Array |Array]]<[[.:common#Int |Int]]>''
 +    ? Example:
 +    :: The following constructs a simple chain complex with only one non-empty differential:
 +    :: <code perl> > $cc = new ChainComplex(new Array<SparseMatrix<Integer>>([[[2,0]]]));
 +</code>
 +    ::  You can print its betti numbers like this:
 +    :: <code perl> > print betti_numbers($cc);
 + 1 0
 +</code>
 +  ?  **''betti_numbers<Coeff>([[.:topaz:SimplicialComplex |SimplicialComplex]] S)''**
 +  :: Calculate the reduced betti numbers of a simplicial complex over a field.
 +    ? Type Parameters:
 +    :: ''Coeff'': The coefficient field type for homology computation. Defaults to Rational
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''S''
 +    ? Returns:
 +    :''[[.:common#Array |Array]]<[[.:common#Int |Int]]>''
 +    ? Example:
 +    :: To print the betti numbers for the torus, do this:
 +    :: <code perl> > $t = torus();
 + > print betti_numbers($t);
 + 0 2 1
 +</code>
 +
 +
 +----
 +{{anchor:cap_product:}}
 +  ?  **''cap_product([[.:topaz#CycleGroup |CycleGroup]]<E> cocycles, [[.:topaz#CycleGroup |CycleGroup]]<E> cycles)''**
 +  :: Compute all cap products of cohomology and homology cycles in two given groups.
 +    ? Parameters:
 +    :: ''[[.:topaz#CycleGroup |CycleGroup]]<E>'' ''cocycles''
 +    :: ''[[.:topaz#CycleGroup |CycleGroup]]<E>'' ''cycles''
 +    ? Returns:
 +    :''[[.:common#Pair |Pair]]<[[.:topaz#CycleGroup |CycleGroup]]<E>,[[.:common#Map |Map]]<[[.:common#Pair |Pair]]<[[.:common#Int |Int]],[[.:common#Int |Int]]>,[[.:common#Int |Int]]%%>>%%''
 +    ? Example:
 +    :: The following stores all cap products of the cocycles and cycles  of the homology group of the oriented surface of genus 1 in the variable $cp.
 +    :: <code perl> > $s = surface(1);
 + > $cp = cap_product($s->COCYCLES->[1],$s->CYCLES->[1]);
 +</code>
 +
 +
 +----
 +{{anchor:homology:}}
 +  ?  **''homology([[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%% complex, [[.:common#Bool |Bool]] co)''**
 +  :: Calculate the reduced __(co-)homology groups__ of a simplicial complex.
 +    ? Parameters:
 +    :: ''[[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%%'' ''complex''
 +    :: ''[[.:common#Bool |Bool]]'' ''co'': set to true for __co__homology
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''dim_low'': narrows the dimension range of interest, with negative values being treated as co-dimensions
 +    :: ''[[.:common#Int |Int]]'' ''dim_high'': see //dim_low//
 +  ?  **''homology([[.:topaz#ChainComplex |ChainComplex]] CC, [[.:common#Bool |Bool]] co)''**
 +  :: Calculate the __(co-)homology groups__ of a chain complex.
 +    ? Parameters:
 +    :: ''[[.:topaz#ChainComplex |ChainComplex]]'' ''CC'': The chain complex for which to compute homology.
 +    :: ''[[.:common#Bool |Bool]]'' ''co'': set to true for __co__homology
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''dim_low'': narrows the dimension range of interest, with negative values being treated as co-dimensions
 +    :: ''[[.:common#Int |Int]]'' ''dim_high'': see //dim_low//
 +    ? Returns:
 +    :''[[.:common#Array |Array]]<[[.:topaz#HomologyGroup |HomologyGroup]]<[[.:common#Integer |Integer]]%%>>%%''
 +    ? Example:
 +    :: To construct a small chain complex with only one non-zero differential:
 +    :: <code perl> > $cc = new ChainComplex(new Array<SparseMatrix<Integer>>([[[2,0]]]));
 +</code>
 +    ::  This prints its homology groups.
 +    :: <code perl> > print homology($cc,0);
 + ({(2 1)} 1)
 + ({} 0)
 +</code>
 +    ::  The output means that the zeroth homology group has 2-torsion with multiplicity one, and betti number one. The first homology group is empty.
 +
 +
 +----
 +{{anchor:homology_and_cycles:}}
 +  ?  **''homology_and_cycles([[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%% complex, [[.:common#Bool |Bool]] co)''**
 +  :: Calculate the reduced __(co-)homology groups__ and __cycle representatives__ of a simplicial complex.
 +    ? Parameters:
 +    :: ''[[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%%'' ''complex''
 +    :: ''[[.:common#Bool |Bool]]'' ''co'': set to true for __co__homology
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''dim_low'': narrows the dimension range of interest, with negative values being treated as co-dimensions
 +    :: ''[[.:common#Int |Int]]'' ''dim_high'': see //dim_low//
 +  ?  **''homology_and_cycles([[.:topaz#ChainComplex |ChainComplex]]<[[.:common#SparseMatrix |SparseMatrix]]<[[.:common#Integer |Integer]]%%>>%% CC, [[.:common#Bool |Bool]] co)''**
 +  :: Calculate the __(co-)homology groups__ and __cycle coefficient matrices__ of a chain complex.
 +    ? Parameters:
 +    :: ''[[.:topaz#ChainComplex |ChainComplex]]<[[.:common#SparseMatrix |SparseMatrix]]<[[.:common#Integer |Integer]]%%>>%%'' ''CC'': The chain complex for which to compute homology.
 +    :: ''[[.:common#Bool |Bool]]'' ''co'': set to true for __co__homology
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''dim_low'': narrows the dimension range of interest, with negative values being treated as co-dimensions
 +    :: ''[[.:common#Int |Int]]'' ''dim_high'': see //dim_low//
 +    ? Returns:
 +    :''[[.:common#Array |Array]]<[[.:common#Pair |Pair]]<[[.:topaz#HomologyGroup |HomologyGroup]],[[.:common#SparseMatrix |SparseMatrix]]%%>>%%''
 +    ? Example:
 +    :: To construct a small chain complex with only one non-zero differential:
 +    :: <code perl> > $cc = new ChainComplex(new Array<SparseMatrix<Integer>>([[[2,0]]]));
 +</code>
 +    ::  This prints its homology groups and corresponding generators.
 +    :: <code perl> > print homology_and_cycles($cc,0);
 + (({(2 1)} 1)
 + <1 0
 + 0 1
 + >
 + )
 + (({} 0)
 + <>
 + )
 +</code>
 +    ::  The output means that the zeroth homology group has 2-torsion with multiplicity one generated by the first elemen of the chain group, and free part of rank one generated by the second element. The first homology group is empty.
 +
 +
 +----
 +{{anchor:homology_flint:}}
 +  ?  **''homology_flint([[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%% complex, [[.:common#Bool |Bool]] co)''**
 +  :: Calculate the reduced __(co-)homology groups__ of a simplicial complex.
 +    ? Parameters:
 +    :: ''[[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%%'' ''complex''
 +    :: ''[[.:common#Bool |Bool]]'' ''co'': set to true for __co__homology
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''dim_low'': narrows the dimension range of interest, with negative values being treated as co-dimensions
 +    :: ''[[.:common#Int |Int]]'' ''dim_high'': see //dim_low//
 +    ? from extension:
 +    : [[:external_software|bundled:flint]]
 +  ?  **''homology_flint([[.:topaz#ChainComplex |ChainComplex]] CC, [[.:common#Bool |Bool]] co)''**
 +  :: Calculate the __(co-)homology groups__ of a chain complex.
 +    ? Parameters:
 +    :: ''[[.:topaz#ChainComplex |ChainComplex]]'' ''CC'': The chain complex for which to compute homology.
 +    :: ''[[.:common#Bool |Bool]]'' ''co'': set to true for __co__homology
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''dim_low'': narrows the dimension range of interest, with negative values being treated as co-dimensions
 +    :: ''[[.:common#Int |Int]]'' ''dim_high'': see //dim_low//
 +    ? Returns:
 +    :''[[.:common#Array |Array]]<[[.:topaz#HomologyGroup |HomologyGroup]]<[[.:common#Integer |Integer]]%%>>%%''
 +    ? from extension:
 +    : [[:external_software|bundled:flint]]
 +    ? Example:
 +    :: To construct a small chain complex with only one non-zero differential:
 +    :: <code perl> > $cc = new ChainComplex(new Array<SparseMatrix<Integer>>([[[2,0]]]));
 +</code>
 +    ::  This prints its homology groups.
 +    :: <code perl> > print homology_flint($cc,0);
 + ({(2 1)} 1)
 + ({} 0)
 +</code>
 +    ::  The output means that the zeroth homology group has 2-torsion with multiplicity one, and betti number one. The first homology group is empty.
 +
 +
 +----
 +
 +==== Other ====
 + Special purpose functions.
 +----
 +{{anchor:dualoutitudepolynomials:}}
 +  ?  **''dualOutitudePolynomials([[.:common#Matrix |Matrix]]<[[.:common#Int |Int]]> dcel_data)''**
 +  :: Given a triangulation of a punctured surface this calculates all the outitude polynomials of the dual structure. The first e = {oriented edges} monomials correspond to A-coordinates of the oriented edges of the primal structure , labeled as in the input. The last t = {triangles} monomials correspond to A-coordinates of the triangles of the primal structure.
 +    ? Parameters:
 +    :: ''[[.:common#Matrix |Matrix]]<[[.:common#Int |Int]]>'' ''dcel_data'': the data for the doubly connected edge list representing the triangulation.
 +    ? Returns:
 +    :''[[.:common#Array |Array]]<[[.:common#Polynomial |Polynomial]]<[[.:common#Rational |Rational]],[[.:common#Int |Int]]%%>>%%''
 +
 +
 +----
 +{{anchor:flips_to_canonical_triangulation:}}
 +  ?  **''flips_to_canonical_triangulation([[.:common#Matrix |Matrix]]<[[.:common#Int |Int]]> DCEL_data, [[.:common#Vector |Vector]]<[[.:common#Rational |Rational]]> A_coords)''**
 +  :: Computes a flip sequence to a canonical triangulation (first list). The second output is a list of flat edges in the canonical triangulation.
 +    ? Parameters:
 +    :: ''[[.:common#Matrix |Matrix]]<[[.:common#Int |Int]]>'' ''DCEL_data''
 +    :: ''[[.:common#Vector |Vector]]<[[.:common#Rational |Rational]]>'' ''A_coords''
 +    ? Returns:
 +    :''[[.:common#Pair |Pair]]<[[.:common#List |List]]<[[.:common#Int |Int]]>,[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%%''
 +    ? Example:
 +    :: In the following example only edge 2 has negative outitude, so the flip sequence should start with 2. After performing this flip, the triangulation thus obtained is canonical.
 +    :: <code perl> > $T1 = new Matrix<Int>([[0,0,2,3,0,1],[0,0,4,5,0,1],[0,0,0,1,0,1]]);
 + > print flips_to_canonical_triangulation($T1,[1,2,3,4,5,6,1,2]);
 + {2} {}
 +</code>
 +
 +
 +----
 +{{anchor:grass_plucker:}}
 +  ?  **''grass_plucker([[.:topaz:SimplicialComplex |SimplicialComplex]] S)''**
 +  :: Combinatorial search for Grassmann-Plucker tree certificates as described in J. Pfeifle, Positive Plücker tree certificates for non-realizability, Experimental Math. 2022 https://doi.org/10.1080/10586458.2021.1994487 and J. Pfeifle, A polymake implementation of Positive Plücker tree certificates for non-realizability, MEGA 2022
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''S''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''verbosity'': default 1, max 2
 +    :: ''[[.:common#Int |Int]]'' ''max_n_undetermined'': the maximal allowed number of undetermined solids in a GP relation. Default 3
 +    :: ''[[.:common#Int |Int]]'' ''abort_after'': stop the computation after how many trees. Default 10000000
 +    :: ''[[.:common#Int |Int]]'' ''tree_log_interval'': after how many trees a log message occurs. Default 10000
 +    :: ''[[.:common#Int |Int]]'' ''cube_log_interval'': after how many cubes a log message occurs. Default 100
 +    ? Returns:
 +    :''[[.:topaz:GrassPluckerCertificate |GrassPluckerCertificate]]''
 +
 +
 +----
 +{{anchor:is_generalized_shelling:}}
 +  ?  **''is_generalized_shelling([[.:common#Array |Array]]<[[.:common#Set |Set]]> FaceList)''**
 +  :: Check if a given sequence of faces of a simplicial complex is a generalized shelling.
 +    ? Parameters:
 +    :: ''[[.:common#Array |Array]]<[[.:common#Set |Set]]>'' ''FaceList''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''verbose''
 +    ? Returns:
 +    :''[[.:common#Bool |Bool]]''
 +
 +
 +----
 +{{anchor:is_vertex_decomposition:}}
 +  ?  **''is_vertex_decomposition([[.:topaz:SimplicialComplex |SimplicialComplex]] complex, [[.:common#Array |Array]]<[[.:common#Int |Int]]> vertices)''**
 +  :: Check whether a given ordered subset of the vertex set is a __vertex decomposition__. Works for 1-, 2- and 3-manifolds only!
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    :: ''[[.:common#Array |Array]]<[[.:common#Int |Int]]>'' ''vertices'': shedding vertices
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Bool |Bool]]'' ''verbose''
 +    ? Returns:
 +    :''[[.:common#Bool |Bool]]''
 +
 +
 +----
 +{{anchor:mixed_graph:}}
 +  ?  **''mixed_graph([[.:topaz:SimplicialComplex |SimplicialComplex]] complex)''**
 +  :: Produces the mixed graph of a //complex//.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Float |Float]]'' ''edge_weight''
 +
 +
 +----
 +{{anchor:outitudepolynomials:}}
 +  ?  **''outitudePolynomials([[.:common#Matrix |Matrix]]<[[.:common#Int |Int]]> dcel_data)''**
 +  :: Given a triangulation of a punctured surface this calculates all the outitude polynomials. The first e = {oriented edges} monomials correspond to A-coordinates of the oriented edges, labeled as in the input. The last t = {triangles} monomials correspond to A-coordinates of the triangles.
 +    ? Parameters:
 +    :: ''[[.:common#Matrix |Matrix]]<[[.:common#Int |Int]]>'' ''dcel_data'': the data for the doubly connected edge list representing the triangulation.
 +    ? Returns:
 +    :''[[.:common#Array |Array]]<[[.:common#Polynomial |Polynomial]]<[[.:common#Rational |Rational]],[[.:common#Int |Int]]%%>>%%''
 +    ? Example:
 +    :: We may calculate the outitude polynomials of a thrice punctured sphere. Here the first six monomials x_0, ... , x_5 are associated to the six oriented edges, x_6 and x_7 are associated to the triangles enclosed by the oriented edges 0,2,4 and 1,3,5 respectively.
 +    :: <code perl> > $S3 = new Matrix<Int>([[1,0,2,5,0,1],[2,1,4,1,0,1],[0,2,0,3,0,1]]);;
 + > print outitudePolynomials($S3);
 + - x_0*x_1*x_6 - x_0*x_1*x_7 + x_0*x_2*x_6 + x_0*x_2*x_7 + x_1*x_5*x_6 + x_1*x_5*x_7 x_1*x_3*x_6 + x_1*x_3*x_7 - x_2*x_3*x_6 - x_2*x_3*x_7 + x_2*x_4*x_6 + x_2*x_4*x_7 x_0*x_4*x_6 + x_0*x_4*x_7 + x_3*x_5*x_6 + x_3*x_5*x_7 - x_4*x_5*x_6 - x_4*x_5*x_7
 +</code>
 +
 +
 +----
 +{{anchor:persistent_homology:}}
 +  ?  **''persistent_homology([[.:topaz#Filtration |Filtration]]<[[.:common#Matrix |Matrix]]<//Scalar//%%>>%% F, [[.:common#Int |Int]] i, [[.:common#Int |Int]] p, [[.:common#Int |Int]] k)''**
 +  :: Given a Filtration and three indices i,p and k, this computes the p-persistent k-th homology group of the i-th frame of the filtration for coefficients from any PID. Returns a basis for the free part and a list of torsion coefficients with bases.
 +    ? Parameters:
 +    :: ''[[.:topaz#Filtration |Filtration]]<[[.:common#Matrix |Matrix]]<//Scalar//%%>>%%'' ''F''
 +    :: ''[[.:common#Int |Int]]'' ''i'': the filtration frame
 +    :: ''[[.:common#Int |Int]]'' ''p'': the number of frames to consider
 +    :: ''[[.:common#Int |Int]]'' ''k'': the dimension in which to compute
 +    ? Returns:
 +    :''[[.:common#Pair |Pair]]<[[.:common#SparseMatrix |SparseMatrix]]<//Scalar//>,[[.:common#List |List]]<[[.:common#Pair |Pair]]<//Scalar//,[[.:common#SparseMatrix |SparseMatrix]]<//Scalar//%%>>%%%%>>%%''
 +  ?  **''persistent_homology([[.:topaz#Filtration |Filtration]] F)''**
 +  :: Given a Filtration, this computes its persistence barcodes in all dimension, using the algorithm described in the 2005 paper 'Computing Persistent Homology' by Afra Zomorodian and Gunnar Carlsson. It only works for field coefficients.
 +    ? Parameters:
 +    :: ''[[.:topaz#Filtration |Filtration]]'' ''F''
 +    ? Returns:
 +    :''[[.:common#Array |Array]]<[[.:common#List |List]]<[[.:common#Pair |Pair]]<[[.:common#Int |Int]],[[.:common#Int |Int]]%%>>%%>''
 +
 +
 +----
 +{{anchor:random_discrete_morse:}}
 +  ?  **''random_discrete_morse([[.:topaz:SimplicialComplex |SimplicialComplex]] complex)''**
 +  :: Implementation of random discrete Morse algorithms by Lutz and Benedetti Returns a map of the number of occurrences of different reduction results indexed by the corresponding discrete Morse vectors (containing the number of critical cells per dimension)
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''rounds'': Run for //r// rounds
 +    :: ''[[.:common#Int |Int]]'' ''seed'': Set seed number for random number generator
 +    :: ''[[.:common#Int |Int]]'' ''strategy'': Set //strategy//=>0 (default) for random-random: uniformly random selecting of a face to collapse or as critical face               Set //strategy//=>1 for random-lex-first: uniformly random relabeling of vertices, then selecting lexicographically first face for collapse or as a critical face               Set //strategy//=>2 for random-lex-last: uniformly random relabeling of vertices, then selecting lexicographically last face for collapse or as a critical face
 +    :: ''[[.:common#Int |Int]]'' ''verbose'': //v// Prints message after running every //v// rounds
 +    :: ''[[.:common#Array |Array]]<[[.:common#Int |Int]]>'' ''try_until_reached'': Used together with //rounds//=>r; When //try_until_reached//=>[a,...,b], runs for //r// rounds or until [a,...,b] is found
 +    :: ''[[.:common#Array |Array]]<[[.:common#Int |Int]]>'' ''try_until_exception'': Used together with //rounds//=>r; When //try_until_exception//=>[a,...,b], runs for //r// rounds or until anything other than [a,...,b] is found
 +    :: ''[[.:common#String |String]]'' ''save_collapsed'': In every round, save all facets that remain after initial collapse in a data file as a ''[[.:topaz:SimplicialComplex |SimplicialComplex]]''. Rounds that have Morse vector [1,0,...,0] or [1,0,...,0,1] will save nothing. The actual file names are <filename>_<currentround>.top
 +    ? Returns:
 +    :''[[.:common#Map |Map]]<[[.:common#Array |Array]]<[[.:common#Int |Int]]>,[[.:common#Int |Int]]>''
 +    ? Example:
 +    :: The example below runs five rounds on the 5-simplex and in all cases returns a discrete Morse function with a single critical vertex.
 +    :: <code perl> > print random_discrete_morse(simplex(5), rounds => 5);
 + {(<1 0 0 0 0 0> 5)}
 +</code>
 +
 +
 +----
 +{{anchor:second_barycentric_subdivision:}}
 +  ?  **''second_barycentric_subdivision([[.:graph:Lattice |Lattice]] L)''**
 +  :: Create the list of faces of the second barycentric subdivision
 +    ? Parameters:
 +    :: ''[[.:graph:Lattice |Lattice]]'' ''L'': (for example, a HASSE_DIAGRAM)
 +    ? Returns:
 +    :''[[.:common#Pair |Pair]]<[[.:common#Array |Array]]<[[.:common#Set |Set]]>,[[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Set |Set]]%%>>%%>''
 +  ?  **''second_barycentric_subdivision([[.:polytope:Polytope |Polytope]] P)''**
 +  :: Create the list of faces of the second barycentric subdivision
 +    ? Parameters:
 +    :: ''[[.:polytope:Polytope |Polytope]]'' ''P'': or SimplicialComplex S
 +    ? Returns:
 +    :''[[.:common#Pair |Pair]]<[[.:common#Array |Array]]<[[.:common#Set |Set]]>,[[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Set |Set]]%%>>%%>''
 +
 +
 +----
 +{{anchor:stabbing_order:}}
 +  ?  **''stabbing_order([[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]] P)''**
 +  :: Determine the stabbing partial order of a simplicial ball with respect to the origin. The origin may be a vertex or not. For details see Assarf, Joswig & Pfeifle: Webs of stars or how to triangulate sums of polytopes, to appear
 +    ? Parameters:
 +    :: ''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]'' ''P''
 +    ? Returns:
 +    :''[[.:graph:Graph |Graph]]<[[.:common#Directed |Directed]]>''
 +
 +
 +----
 +{{anchor:stanley_reisner:}}
 +  ?  **''stanley_reisner([[.:topaz:SimplicialComplex |SimplicialComplex]] complex)''**
 +  :: Creates the __Stanley-Reisner ideal__ of a simplicial complex.
 +    ? Parameters:
 +    :: ''[[.:topaz:SimplicialComplex |SimplicialComplex]]'' ''complex''
 +    ? Returns:
 +    :''[[.:ideal:Ideal |Ideal]]''
 +    ? Example:
 +    :: <code perl> > $s = new SimplicialComplex(INPUT_FACES=>[[0, 1], [0, 2], [1, 2], [2, 3]]);
 + > $i = stanley_reisner($s);
 + > print $i -> GENERATORS;
 + x_0*x_3 x_1*x_3 x_0*x_1*x_2
 +</code>
 +
 +
 +----
 +{{anchor:star_of_zero:}}
 +  ?  **''star_of_zero([[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]] C)''**
 +  :: Find the facets of the star of the origin in the simplicial complex. The origin may be a vertex or not. For details see Assarf, Joswig & Pfeifle: Webs of stars or how to triangulate sums of polytopes, to appear
 +    ? Parameters:
 +    :: ''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]'' ''C''
 +    ? Returns:
 +    :''[[.:common#Set |Set]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%%''
 +
 +
 +----
 +{{anchor:star_shaped_balls:}}
 +  ?  **''star_shaped_balls([[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]] P)''**
 +  :: Enumerate all balls formed by the simplices of a geometric simplicial complex that are strictly star-shaped with respect to the origin. The origin may be a vertex or not. For details see Assarf, Joswig & Pfeifle: Webs of stars or how to triangulate sums of polytopes, to appear
 +    ? Parameters:
 +    :: ''[[.:topaz:GeometricSimplicialComplex |GeometricSimplicialComplex]]'' ''P''
 +    ? Returns:
 +    :''[[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Set |Set]]%%>>%%''
 +
 +
 +----
 +{{anchor:stiefel_whitney:}}
 +  ?  **''stiefel_whitney([[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%% facets)''**
 +  :: Computes __Stiefel-Whitney homology classes__ of mod 2 Euler space (in particular, closed manifold). See Richard Z. Goldstein and Edward C. Turner, Proc. Amer. Math. Soc., 58:339-342 (1976) Use option //verbose// to show regular pairs and cycles. A narrower dimension range of interest can be specified. Negative values are treated as co-dimension - 1
 +    ? Parameters:
 +    :: ''[[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%%'' ''facets'': the facets of the simplicial complex
 +    ? Options:
 +    : 
 +    :: ''[[.:common#Int |Int]]'' ''high_dim''
 +    :: ''[[.:common#Int |Int]]'' ''low_dim''
 +    :: ''[[.:common#Bool |Bool]]'' ''verbose''
 +    ? Returns:
 +    :''[[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%%>''
 +
 +
 +----
 +{{anchor:vietoris_rips_filtration:}}
 +  ?  **''vietoris_rips_filtration<Coeff>([[.:common#Matrix |Matrix]] D, [[.:common#Array |Array]]<[[.:common#Int |Int]]> deg, [[.:common#Float |Float]] step_size, [[.:common#Int |Int]] k)''**
 +  :: Constructs the k-skeleton of the Vietrois Rips filtration of a point set. The set is passed as its so-called "distance matrix", whose (i,j)-entry is the distance between point i and j. This matrix can e.g. be computed using the distance_matrix function. The other inputs are an integer array containing the degree of each point, the desired distance step size between frames, and the dimension up to which to compute the skeleton. Redundant points will appear as separate vertices of the complex. Setting k to |S| will compute the entire VR-Complex for each frame.
 +    ? Type Parameters:
 +    :: ''Coeff'': desired coefficient type of the filtration
 +    ? Parameters:
 +    :: ''[[.:common#Matrix |Matrix]]'' ''D'': the "distance matrix" of the point set (can be upper triangular)
 +    :: ''[[.:common#Array |Array]]<[[.:common#Int |Int]]>'' ''deg'': the degrees of input points
 +    :: ''[[.:common#Float |Float]]'' ''step_size''
 +    :: ''[[.:common#Int |Int]]'' ''k'': dimension of the resulting filtration
 +    ? Returns:
 +    :''[[.:topaz#Filtration |Filtration]]<[[.:common#SparseMatrix |SparseMatrix]]<Coeff,[[.:common#NonSymmetric |NonSymmetric]]%%>>%%''
 +
 +
 +----
 +
 +===== Small Object Types =====
 +
 +==== Topology ====
 + The following property_types are topological invariants.
 +----
 +{{anchor:cell:}}
 +  ?  **''Cell''**
 +  ::
 +
 +
 +----
 +{{anchor:chaincomplex:}}
 +  ?  **''ChainComplex<MatrixType>''**
 +  :: A finite chain complex, represented as its boundary matrices. Check out the tutorial on the polymake homepage for examples on constructing ChainComplexes and computing their homology.
 +    ? Type Parameters:
 +    :: ''MatrixType'': The type of the differential matrices. default: SparseMatrix<Integer>
 +    ? Example:
 +    :: You can create a new ChainComplex by passing the Array of differential matrices (as maps via _left_ multiplication):
 +    :: <code perl> > $cc = new ChainComplex(new Array<SparseMatrix<Integer>>([[[2,0]]]));
 +</code>
 +    ::  Note that this creates a ChainComplex consisting three differential matrices -- the trivial zeroth and last ones are omitted in the constructor. You can look at the boundary matrices:
 +    :: <code perl> > print $cc->boundary_matrix(1);
 + 2 0
 +</code>
 +    ::  The functions ''homology'', ''homology_and_cycles'' and ''betti_numbers'' can be used to analyse your complex.
 +    :: <code perl> > print homology($cc,0);
 + ({(2 1)} 1)
 + ({} 0)
 +</code>
 +    ? Methods of ChainComplex:
 +    :
 +      ?  **''boundary_matrix([[.:common#Int |Int]] d)''**
 +      :: Returns the d-boundary matrix of the chain complex.
 +        ? Parameters:
 +        :: ''[[.:common#Int |Int]]'' ''d''
 +        ? Returns:
 +        :''MatrixType''
 +      ?  **''dim()''**
 +      :: Returns the number of non-empty modules in the complex.
 +        ? Returns:
 +        :''[[.:common#Int |Int]]''
 +
 +
 +----
 +{{anchor:cyclegroup:}}
 +  ?  **''CycleGroup<Scalar>''**
 +  :: A group is encoded as a pair of an integer matrix and a vector of faces. The elements of the group can be obtained by symbolic multiplication of both.
 +    ? Type Parameters:
 +    :: ''Scalar'': integer type of matrix elements
 +    ? Methods of CycleGroup:
 +    :
 +      ?  **''coeff()''**
 +      ::the integer matrix
 +        ? Returns:
 +        :''[[.:common#SparseMatrix |SparseMatrix]]<Scalar>''
 +      ?  **''faces()''**
 +      ::the faces
 +        ? Returns:
 +        :''[[.:common#Array |Array]]<[[.:common#Set |Set]]<[[.:common#Int |Int]]%%>>%%''
 +
 +
 +----
 +{{anchor:filtration:}}
 +  ?  **''Filtration<MatrixType>''**
 +  :: A filtration of chain complexes.
 +    ? Type Parameters:
 +    :: ''MatrixType''
 +    ? Methods of Filtration:
 +    :
 +      ?  **''boundary_matrix([[.:common#Int |Int]] d, [[.:common#Int |Int]] t)''**
 +      :: Returns the d-boundary matrix of the t-th frame of the filtration.
 +        ? Parameters:
 +        :: ''[[.:common#Int |Int]]'' ''d''
 +        :: ''[[.:common#Int |Int]]'' ''t''
 +      ?  **''cells()''**
 +      :: Returns the cells of the filtration, given as array of 3-tuples containing degree, dimension and boundary matrix row number of the cell.
 +        ? Returns:
 +        :''[[.:common#Array |Array]]<[[.:topaz#Cell |Cell]]>''
 +      ?  **''dim()''**
 +      :: Returns the dimension of the maximal cells in the last frame of the filtration.
 +        ? Returns:
 +        :''[[.:common#Int |Int]]''
 +      ?  **''n_cells()''**
 +      :: Returns the number of cells in the last frame of the filtration.
 +        ? Returns:
 +        :''[[.:common#Int |Int]]''
 +      ?  **''n_frames()''**
 +      :: Returns the number of frames in of the filtration.
 +        ? Returns:
 +        :''[[.:common#Int |Int]]''
 +
 +
 +----
 +{{anchor:homologygroup:}}
 +  ?  **''HomologyGroup<Scalar>''**
 +  :: A finitely generated abelian group is encoded as a sequence ( { (t<sub>1</sub> m<sub>1</sub>) ...  (t<sub>n</sub>  m<sub>n</sub>) } f) of non-negative integers, with t<sub>1</sub> > t<sub>2</sub> > ... > t<sub>n</sub> > 1, plus an extra non-negative integer f. That group is isomorphic to (Z/t<sub>1</sub>)<sup>m<sub>1</sub></sup> × ... × (Z/t<sub>n</sub>)<sup>m<sub>n</sub></sup> × Z<sup>f</sup>,  where Z<sup>0</sup> is the trivial group.
 +    ? Type Parameters:
 +    :: ''Scalar'': integer type of torsion coefficients
 +    ? Methods of HomologyGroup:
 +    :
 +      ?  **''betti_number()''**
 +      ::the number //f//
 +        ? Returns:
 +        :''[[.:common#Int |Int]]''
 +      ?  **''torsion()''**
 +      ::list of Z-groups
 +        ? Returns:
 +        :''[[.:common#List |List]]<[[.:common#Pair |Pair]]<Scalar,[[.:common#Int |Int]]%%>>%%''
 +
 +
 +----
 +{{anchor:intersectionform:}}
 +  ?  **''IntersectionForm''**
 +  :: Parity and signature of the intersection form of a closed oriented 4k-manifold. See ''[[.:topaz:SimplicialComplex#INTERSECTION_FORM |INTERSECTION_FORM]]''.
 +
 +
 +----