regina::NLayering Class Reference
Standard Triangulations and Subcomplexes

Represents a layering of zero or more tetrahedra upon a torus boundary. More...

`#include <subcomplex/nlayering.h>`

Inheritance diagram for regina::NLayering:

## Public Member Functions

| NLayering (NTetrahedron *bdry0, NPerm4 roles0, NTetrahedron *bdry1, NPerm4 roles1)
| Creates a new trivial (zero-tetrahedron) layering upon the given boundary. More...
unsigned long | getSize () const
| Returns the number of individual tetrahedra that have been layered onto the original boundary, according to the data stored in this structure. More...
NTetrahedron * | getOldBoundaryTet (unsigned which) const
| Returns the tetrahedra that provide the old boundary triangles. More...
NPerm4 | getOldBoundaryRoles (unsigned which) const
| Returns the permutations that describe the old boundary triangles. More...
NTetrahedron * | getNewBoundaryTet (unsigned which) const
| Returns the tetrahedra that provide the new boundary triangles. More...
NPerm4 | getNewBoundaryRoles (unsigned which) const
| Returns the permutations that describe the new boundary triangles. More...
const NMatrix2 & | boundaryReln () const
| Returns a 2-by-2 matrix describing the relationship between curves on the old and new boundary tori. More...
bool | extendOne ()
| Examines whether a single additional tetrahedron has been layered upon the current new boundary. More...
unsigned long | extend ()
| Examines whether one or more additional tetrahedra have been layered upon the current new boundary. More...
bool | matchesTop (NTetrahedron *upperBdry0, NPerm4 upperRoles0, NTetrahedron *upperBdry1, NPerm4 upperRoles1, NMatrix2 &upperReln) const
| Determines whether the new torus boundary of this structure is identified with the given torus boundary. More...

## Additional Inherited Members

Protected Member Functions inherited from regina::boost::noncopyable
| noncopyable ()
| A constructor which does nothing. More...
| ~noncopyable ()
| A destructor which does nothing. More...

## Detailed Description

Represents a layering of zero or more tetrahedra upon a torus boundary.

A layering involves laying a new tetrahedron flat upon two adjacent boundary triangles in order to change the boundary curves. Many tetrahedra may be layered upon a boundary in succession in order to change the boundary curves more dramatically.

A torus boundary is specified by two tetrahedra (which may be the same) and two permutations. Each permutation maps (0,1,2) in the diagram below to the corresponding vertex numbers in each tetrahedron (and therefore maps 3 to the corresponding face number).

        *--->>--*
        |0  2 / |
        |    / 1|
        v   /   v
        |1 /    |
        | / 2  0|
        *--->>--*

In particular, if the two tetrahedra are t0 and t1 and the two corresponding permutations are p0 and p1, then:

- the torus boundary is formed from faces p0[3] and p1[3] of tetrahedra t0 and t1 respectively;
- edges p0[0]-p0[1] and p1[1]-p1[0] of tetrahedra t0 and t1 respectively are identified;
- edges p0[1]-p0[2] and p1[2]-p1[1] of tetrahedra t0 and t1 respectively are identified;
- edges p0[2]-p0[0] and p1[0]-p1[2] of tetrahedra t0 and t1 respectively are identified.

Note that we do not actually require these triangular faces to form a torus, and this is never verifed by any of the routines in this class. What these routines do is use the diagram above to define the rules of what forms a valid layering (and in fact the layering itself will often be the cause of these edge identifications). This allows the NLayering class a little more versatility in degenerate and boundary cases.

This class keeps track of an old boundary, which is the original pair of triangles upon which the first tetrahedron is layered, and a new boundary, which is formed by the last layered tetrahedron and contains the modified boundary curves. If no tetrahedra are layered at all then the old and new boundaries will be identical.

This class is used to search for layerings as follows. The constructor is called with a particular pair of triangles that will form the old boundary (note that these are generally not boundary triangles in the triangulation, since we are searching for layerings that have been placed upon them). This forms a trivial (zero-tetrahedron) layering. The routines extend() or extendOne() are then called to see how many additional tetrahedra have been layered upon this pair of triangles according to the rules above.

## Constructor & Destructor Documentation

regina::NLayering::NLayering | ( | NTetrahedron * | bdry0,
|  | NPerm4 | roles0,
|  | NTetrahedron * | bdry1,
|  | NPerm4 | roles1
| ) |  |

Creates a new trivial (zero-tetrahedron) layering upon the given boundary.

The boundary is described by two tetrahedra and two permutations as explained in the class notes. Note that the given tetrahedra need not be boundary triangles in the triangulation (and if search routines such as extend() are called then they almost certainly should not be).

Parameters

  bdry0 | the tetrahedron providing the first triangle of the boundary.
  roles0 | the permutation describing how this first triangle is formed from three vertices of tetrahedron bdry0, as described in the class notes.
  bdry1 | the tetrahedron providing the second triangle of the boundary.
  roles1 | the permutation describing how this second triangle is formed from three vertices of tetrahedron bdry1.

## Member Function Documentation

const NMatrix2 & regina::NLayering::boundaryReln | ( |  | ) | const

inline

Returns a 2-by-2 matrix describing the relationship between curves on the old and new boundary tori.

Note that this relationship will often be non-trivial, since one of the key reasons for layering is to modify boundary curves.

Let t and p be the first tetrahedron and permutation of the old boundary (as returned by getOldBoundaryTet(0) and getOldBoundaryRoles(0)), and let old_x and old_y be the directed edges p[0]-p[1] and p[0]-p[2] respectively of tetrahedron t (these are the leftmost and uppermost edges of the diagram below). Likewise, let s and q be the first tetrahedron and permutation of the new boundary (as returned by getNewBoundaryTet(0) and getNewBoundaryRoles(0)), and let new_x and new_y be the directed edges q[0]-q[1] and q[0]-q[2] respectively of tetrahedron s.

        *--->>--*
        |0  2 / |
        |    / 1|
        v   /   v
        |1 /    |
        | / 2  0|
        *--->>--*

Assuming both boundaries are tori, edges old_x and old_y are generators of the old boundary torus and edges new_x and new_y are generators of the new boundary torus. Suppose that this routine returns the matrix M. This signifies that, using additive notation:

        [new_x]         [old_x]
        [     ]  =  M * [     ] .
        [new_y]         [old_y]

In other words, the matrix that is returned expresses the generator curves of the new boundary in terms of the generator curves of the old boundary.

Note that the determinant of this matrix will always be 1.

Returns
  the matrix relating the old and new boundary curves.

unsigned long regina::NLayering::extend | ( |  | ) |

Examines whether one or more additional tetrahedra have been layered upon the current new boundary.

Specifically, this routine calls extendOne() as many times as possible. If k additional layerings are discovered as a result, the size of this structure will have grown by k and the new boundary will be changed to describe the remaining two faces of the kth layered tetrahedron.

It is guaranteed that, once this routine is finished, the new boundary will not have any additional tetrahedron layered upon it. That is, if extendOne() were called again then it would return `false`.

Returns
  the number of additional layered tetrahedra that were discovered.

bool regina::NLayering::extendOne | ( |  | ) |

Examines whether a single additional tetrahedron has been layered upon the current new boundary.

The new boundary triangles are assumed to form a torus as described in the class notes (this is not verified, and there are degenerate cases where this will likely be false). This defines three possible ways in which an additional tetrahedron may be layered (over the three boundary edges respectively).

If it is found that an additional tetrahedron does exist and has been joined to the new boundary in one of these three possible ways, this structure is extended to incorporate the additional tetrahedron. The size will grow by one, and the new boundary will become the remaining two faces of this additional tetrahedron.

Returns
  `true` if a tetrahedron was found as described above and this structure was extended accordingly, or `false` otherwise.

NPerm4 regina::NLayering::getNewBoundaryRoles | ( | unsigned | which | ) | const

inline

Returns the permutations that describe the new boundary triangles.

These refer to the final boundary after layerings have been performed.

See the NLayering class notes for details on how a torus boundary is formed from two tetrahedra and two permutations.

Parameters

  which | specifies which permutation to return; this must be either 0 or 1.

Returns
  the requested permutation describing the new boundary.

NTetrahedron * regina::NLayering::getNewBoundaryTet | ( | unsigned | which | ) | const

inline

Returns the tetrahedra that provide the new boundary triangles.

These belong to the final boundary after layerings have been performed.

See the NLayering class notes for details on how a torus boundary is formed from two tetrahedra and two permutations.

Parameters

  which | specifies which tetrahedron to return; this must be either 0 or 1.

Returns
  the requested tetrahedron of the new boundary.

NPerm4 regina::NLayering::getOldBoundaryRoles | ( | unsigned | which | ) | const

inline

Returns the permutations that describe the old boundary triangles.

These refer to the original boundary before any layerings take place.

See the NLayering class notes for details on how a torus boundary is formed from two tetrahedra and two permutations.

Parameters

  which | specifies which permutation to return; this must be either 0 or 1.

Returns
  the requested permutation describing the old boundary.

NTetrahedron * regina::NLayering::getOldBoundaryTet | ( | unsigned | which | ) | const

inline

Returns the tetrahedra that provide the old boundary triangles.

These belong to the original boundary before any layerings take place.

See the NLayering class notes for details on how a torus boundary is formed from two tetrahedra and two permutations.

Parameters

  which | specifies which tetrahedron to return; this must be either 0 or 1.

Returns
  the requested tetrahedron of the old boundary.

unsigned long regina::NLayering::getSize | ( |  | ) | const

inline

Returns the number of individual tetrahedra that have been layered onto the original boundary, according to the data stored in this structure.

This begins at zero when the class constructor is called, and it increases if the routines extend() or extendOne() find that additional layerings have taken place.

Returns
  the number of layered tetrahedra.

bool regina::NLayering::matchesTop | ( | NTetrahedron * | upperBdry0,
|  | NPerm4 | upperRoles0,
|  | NTetrahedron * | upperBdry1,
|  | NPerm4 | upperRoles1,
|  | NMatrix2 & | upperReln
| ) |  | const

Determines whether the new torus boundary of this structure is identified with the given torus boundary.

In other words, this routine determines whether the new torus boundary of this structure and the given torus boundary represent opposite sides of the same two triangles.

The two boundaries must be identified according to some homeomorphism of the torus. Note that there are 12 different ways in which this can be done (two choices for which tetrahedron face joins with which, and then six possible rotations and reflections).

As with the other routines in this class, this routine does not verify that either boundary in fact forms a torus. Instead, it uses this assumption to define the rules of what identifications are allowable.

If there is a match, the given matrix upperReln will be modified to describe how the edges of the given boundary relate to the edges of the old boundary torus. Note that this relationship depends on how the intermediate tetrahedra are layered (and in fact the purpose of a layering is often to produce such a non-trivial relationship).

Specifically, let t0 and p0 be the first tetrahedron and permutation of the old boundary (as returned by getOldBoundaryTet(0) and getOldBoundaryRoles(0)), and let x and y be the directed edges p0[0]-p0[1] and p0[0]-p0[2] of tetrahedron t0 respectively (these are the leftmost and uppermost edges of the diagram below). Likewise, let u and q be the first tetrahedron and permutation of the given boundary (as passed by parameters upperBdry0 and upperRoles0), and let a and b be the directed edges q[0]-q[1] and q[0]-q[2] of tetrahedron u respectively.

        *--->>--*
        |0  2 / |
        |    / 1|
        v   /   v
        |1 /    |
        | / 2  0|
        *--->>--*

Assuming both boundaries are tori, edges x and y are generators of the original torus boundary and edges a and b are generators of the given torus boundary. Using additive notation, the matrix upperReln is modified so that

        [a]                 [x]
        [ ]  =  upperReln * [ ] .
        [b]                 [y]

In other words, the modified upperReln matrix expresses the generator curves of the given boundary in terms of the generator curves of the old boundary.

If no match is found, the matrix upperReln is not touched.

Parameters

  upperBdry0 | the tetrahedron providing the first triangle of the given boundary.
  upperRoles0 | the permutation describing how this first triangle is formed from three vertices of tetrahedron upperBdry0, as described in the class notes.
  upperBdry1 | the tetrahedron providing the second triangle of the given boundary.
  upperRoles1 | the permutation describing how this second triangle is formed from three vertices of tetrahedron upperBdry1.
  upperReln | the matrix that is changed to reflect the relationship between the old boundary of this structure and the given boundary.

Returns
  `true` if the given boundary is found to matche the new boundary of this structure, or `false` otherwise.

The documentation for this class was generated from the following file:

- subcomplex/nlayering.h

Copyright © 1999-2013, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@debian.org).