simplex

5reg

simplex

A single top-dimensional simplex in a `dim`-dimensional triangulation

Content Model
    simplex ::= (#PCDATA)
Attributes
Name | Type
`desc` | `CDATA`
`lock` | `NUMBER`

## Description

A &xml-simplex; element stores a single top-dimensional simplex in a `dim`-dimensional triangulation, along with its associated facet gluings. Since ®ina; 7.0, this element is now used by all of the dimensions that ®ina; supports (2 ≤ `dim` ≤ 15).

The character data of this &xml; element should be a whitespace-separated list of `dim` + 1 integer pairs, representing the gluings of facets 0, 1, …, `dim` of this simplex. Note that facet `i` is always opposite vertex `i` in a top-dimensional simplex.

For each pair, the first integer represents the other top-dimensional simplex to which the facet is glued (recall that simplices in a triangulation are numbered 0, 1, 2, etc.). The second integer represents the permutation of vertices from this simplex to the other simplex describing precisely how this gluing takes place. This permutation will take the current facet number of this simplex to the corresponding facet number of the adjacent simplex, and the other `dim` vertex numbers of this simplex to the corresponding `dim` vertex numbers on the adjacent simplex to which they are identified by this gluing.

There are two ways in which ®ina; can encode permutations as integers: indices into the symmetric group S`dim`+1, and image packs. Which of these methods is used is specified by the `perm` attribute of the enclosing &xml-tri; element. If no method is specified (e.g., if this is an older second-generation data file), then ®ina; will assume indices for dimension 2, and image packs for dimensions `dim` ≥ 3 (following the behaviour of the second-generation file format).

- An index encodes a permutation as an integer `i` in the range 0 ≤ `i` < (`dim`+1)!. This integer is the index of the permutation into the symmetric group S`dim`+1. These indices list the permutations in “almost lexicographical” order; the exception is that some pairs (2`i`, 2`i`+1) are swapped to ensure that even indices correspond to even permutations.

  You can access these indices from within ®ina; using the functions `Perm<dim+1>::SnIndex()` and `Perm<dim+1>::Sn[...]`.

- An image pack encodes a permutation as follows. If the permutation maps 0, 1, …, `dim` to `a0`, `a1`, …, `aDim` respectively (where `a0`, `a1`, …, `aDim` are 0, 1, …, `dim` in some order), then the corresponding integer is (`a0` + `B` `a1` + `B` 2 `a2` + … + `B` `dim` `aDim`). Here the “base” `B` is `B` = 4 for dimension `dim` = 3, `B` = 8 for dimensions 4 ≤ `dim` ≤ 7, and `B` = 16 for dimensions 8 ≤ `dim` ≤ 15. As an example, the identity permutation for dimension `dim` = 8 which maps (0,1,…,8) to (0,1,…,8) is represented by the integer (0 + 1×16 + 2×256 + … + 8×4294967296), which is 36344967696.

  You can access these indices from within ®ina; using the functions `Perm<dim+1>::imagePack()` and `Perm<dim+1>::fromImagePack(...)`.

If a facet is a boundary facet (i.e., it is not glued to anything), the two corresponding integers stored in the &xml; character data should be -1 and -1.

For dimensions `dim` = 2..7, permutations are represented by 32-bit integers. In contrast, for dimensions `dim` = 8..15, permutations are represented by 64-bit integers. If you are writing code that reads ®ina; data files, you may need to use a large integer type (such as `long long` in &cpp;) accordingly.

### Parents

The following elements contain `simplex`:

- &xml-tri;

.

### Children

Element `simplex` has no children.

## Attributes

`desc`

- A human-readable description of the role that this top-dimensional simplex plays in the overall triangulation.

`lock`

- A hexadecimal bitmask indicating whether this top-dimensional simplex and/or any of its facets are locked. Essentially, locking a simplex or facet means that the simplex or facet must not change; see ®ina;'s API documentation for full details.

  This bitmask must contain `dim` + 2 bits; here we number the bits so that the 0th bit is least significant. Bit `k` should be set if and only if facet `k` of this simplex is locked, for 0 ≤ `k` ≤ `dim`. Bit `dim` + 1 should be set if and only if this simplex itself is locked.

  If two top-dimensional simplices are glued together, then the corresponding facet locks must be consistent (i.e., the two facets that are joined must either be both locked or both unlocked).

  If this attribute is missing, then the bitmask will be treated as 0 (i.e., the simplex and all of its facets are unlocked).

## Example

The following &xml; snippet represents simplex number 0 in a 6-dimensional triangulation, using image packs to represent permutations. Facet 0 of this simplex is glued to facet 6 of simplex number 1, with a gluing permutation that maps (0,1,2,3,4,5,6) to (6,0,1,2,3,4,5). Facet 6 of this simplex is glued to facet 0 of simplex number 1, with a gluing permutation that maps (0,1,2,3,4,5,6) to (1,2,3,4,5,6,0). The remaining facets 1,…,5 of this simplex are all boundary facets.

    <simplex> 1 14038087 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 1 2054353 </simplex>