regina::NSatAnnulus Struct Reference
Standard Triangulations and Subcomplexes

Represents an annulus formed from a pair of triangles in a Seifert fibred space. More...

`#include <subcomplex/nsatannulus.h>`

## Public Member Functions

| NSatAnnulus ()
| Creates a new uninitialised structure. More...
| NSatAnnulus (const NSatAnnulus &cloneMe)
| Creates a clone of the given structure. More...
| NSatAnnulus (NTetrahedron *t0, NPerm4 r0, NTetrahedron *t1, NPerm4 r1)
| Creates a new structure initialised to the given values. More...
NSatAnnulus & | operator= (const NSatAnnulus &cloneMe)
| Makes this equal to a clone of the given structure. More...
bool | operator== (const NSatAnnulus &other) const
| Determines whether or not this and the given structure describe the same annulus with the same representation. More...
bool | operator!= (const NSatAnnulus &other) const
| Determines whether or not this and the given structure describe the same annulus with the same representation. More...
unsigned | meetsBoundary () const
| Determines how many triangles of this annulus lie on the boundary of the triangulation. More...
void | switchSides ()
| Converts this into a representation of the same annulus from the other side. More...
NSatAnnulus | otherSide () const
| Returns a representation of the same annulus from the other side. More...
void | reflectVertical ()
| Reverses the direction of the vertical fibres in this annulus representation. More...
NSatAnnulus | verticalReflection () const
| Returns a representation of this annulus in which the vertical direction of the fibres has been reversed. More...
void | reflectHorizontal ()
| Performs a left-to-right reflection of this annulus representation. More...
NSatAnnulus | horizontalReflection () const
| Returns a left-to-right reflected representation of this annulus. More...
void | rotateHalfTurn ()
| Rotates the representation of this annulus by 180 degrees. More...
NSatAnnulus | halfTurnRotation () const
| Returns a 180 degree rotated representation of this annulus. More...
bool | isAdjacent (const NSatAnnulus &other, bool *refVert, bool *refHoriz) const
| Determines whether this and the given annulus are adjacent, possibly modulo vertical or horizontal reflections. More...
bool | isJoined (const NSatAnnulus &other, NMatrix2 &matching) const
| Determines whether this and the given annulus are joined in some form, even if the fibres on each annulus are not consistent. More...
bool | isTwoSidedTorus () const
| Determines whether this annulus has its boundaries identified to form an embedded two-sided torus within the surrounding triangulation. More...
void | transform (const NTriangulation *originalTri, const NIsomorphism *iso, NTriangulation *newTri)
| Adjusts this annulus representation according to the given isomorphism between triangulations. More...
NSatAnnulus | image (const NTriangulation *originalTri, const NIsomorphism *iso, NTriangulation *newTri) const
| Returns the image of this annulus representation under the given isomorphism between triangulations. More...
void | attachLST (NTriangulation *tri, long alpha, long beta) const
| Attaches a layered solid torus to the this saturated annulus. More...

## Public Attributes

NTetrahedron * | tet [2]
| Describes which tetrahedra provide the first and second triangles. More...
NPerm4 | roles [2]
| Describes how the first and second triangles match up with individual tetrahedron vertices. More...

## Detailed Description

Represents an annulus formed from a pair of triangles in a Seifert fibred space.

This annulus is saturated, i.e., a union of fibres. More than that, the fibres run parallel to the two boundary edges of the annulus.

The annulus is described from one side only. The description includes an array of indices tet[] describing which two tetrahedra provide the triangles of the annulus, as well as an array of permutations roles[] detailing how the annulus matches up with the individual tetrahedron vertices.

The annulus can be drawn as follows, with the upper edge identified with the lower:

               *--->---*
               |0  2 / |
       First   |    / 1|  Second
      triangle |   /   | triangle
               |1 /    |
               | / 2  0|
               *--->---*

Suppose that tet[0] and tet[1] are the tetrahedra providing the first and second triangles respectively. Then the markings 0..2 on the first triangle above correspond to vertices roles[0][0..2] of tetrahedron tet[0], and likewise the markings 0..2 on the second triangle above correspond to vertices roles[1][0..2] of tetrahedron tet[1].

Note that the diagram above can also be drawn as follows.

               *--->---*
               | \ 2  1|
       First   |0 \    |  Second
      triangle |   \   | triangle
               |    \ 0|
               |1  2 \ |
               *--->---*

Note also that the labelling of the tetrahedra and their vertices establishes an orientation on the vertical fibres, as well as a left-to-right direction across the annulus.

For convenience we refer to edges roles[][0-1] as vertical, edges roles[][0-2] as horizontal, and edge roles[][1-2] as diagonal. This is illustrated in the following diagrams.

            V  Horizontal       V   Diagonal
            e  *--->---*        e  *--->---*
            r  |   g / |        r  |H\ 2  1|
            t  |  a / 1|        t  | o\    |
            i  | i /   |        i  |  r\   |
            c  |D /    |        c  |   i\ 0|
            a  | / 2  0|        a  |    z\ |
            l  *--->---*        l  *--->---*

Python:
  The member arrays tet and roles are accessed for reading through functions tet() and roles() respectively. For instance, the first triangle tetrahedron for the saturated annulus a can be accessed as `a.tet(0)`. These same member arrays are accessed for writing through functions setTet() and setRoles(), so for instance the second triangle vertex roles for the saturated annulus a can be modified by calling `a.setRoles(1, newRoles)`.

## Constructor & Destructor Documentation

regina::NSatAnnulus::NSatAnnulus | ( |  | ) |

inline

Creates a new uninitialised structure.

Both tetrahedra will be set to null pointers.

regina::NSatAnnulus::NSatAnnulus | ( | const NSatAnnulus & | cloneMe | ) |

inline

Creates a clone of the given structure.

Parameters

  cloneMe | the structure to clone.

regina::NSatAnnulus::NSatAnnulus | ( | NTetrahedron * | t0,
|  | NPerm4 | r0,
|  | NTetrahedron * | t1,
|  | NPerm4 | r1
| ) |  |

inline

Creates a new structure initialised to the given values.

See the class notes for what the various tetrahedra and permutations mean.

Parameters

  t0 | the tetrahedron to assign to tet[0].
  r0 | the permutation to assign to roles[0].
  t1 | the tetrahedron to assign to tet[1].
  r1 | the permutation to assign to roles[1].

## Member Function Documentation

void regina::NSatAnnulus::attachLST | ( | NTriangulation * | tri,
|  | long | alpha,
|  | long | beta
| ) |  | const

Attaches a layered solid torus to the this saturated annulus.

The layered solid torus will be attached so that the given values alpha and beta describe how the meridinal disc cuts the vertical and horizontal edges of the annulus respectively.

The result will effectively insert an (alpha, beta) exceptional fibre into the Seifert fibred space space, where the vertical edges run parallel to the fibres and the horizontal edges represent the base orbifold. The sign of the fibre is consistent with the fibre inserted by NSatLST::adjustSFS() (in particular, negating beta will negate the fibre).

In the case of a (2,1) fibre, the layered solid torus will be degenerate (i.e., the two triangles of the annulus will simply be joined together).

Precondition
  The given value alpha is not zero.
  The given values alpha and beta are coprime.

Parameters

  tri | the triangulation into which the new tetrahedra should be inserted.
  alpha | describes how the meridinal disc of the torus should cut the vertical edges. This may be positive or negative.
  beta | describes how the meridinal disc of the torus should cut the horizontal edges. Again this may be positive or negative.

NSatAnnulus regina::NSatAnnulus::halfTurnRotation | ( |  | ) | const

inline

Returns a 180 degree rotated representation of this annulus.

This structure will not be changed. See rotateHalfTurn() for further details.

Returns
  a new 180 degree rotation of this annulus.

NSatAnnulus regina::NSatAnnulus::horizontalReflection | ( |  | ) | const

inline

Returns a left-to-right reflected representation of this annulus.

This structure will not be changed. See reflectHorizontal() for further details.

Returns
  a new left-to-right reflection of this annulus.

NSatAnnulus regina::NSatAnnulus::image | ( | const NTriangulation * | originalTri,
|  | const NIsomorphism * | iso,
|  | NTriangulation * | newTri
| ) |  | const

inline

Returns the image of this annulus representation under the given isomorphism between triangulations.

This annulus representation will not be changed. See transform() for further details.

Parameters

  originalTri | the triangulation currently used by this annulus representation.
  iso | the mapping from originalTri to newTri.
  newTri | the triangulation to be used by the new annulus representation.

bool regina::NSatAnnulus::isAdjacent | ( | const NSatAnnulus & | other,
|  | bool * | refVert,
|  | bool * | refHoriz
| ) |  | const

Determines whether this and the given annulus are adjacent, possibly modulo vertical or horizontal reflections.

That is, this routine determines whether this and the given structure represent opposite sides of the same saturated annulus, where the fibres for both structures are consistent (though possibly reversed). See switchSides() for details on what "opposite sides" means in this context, and see reflectVertical() and reflectHorizontal() for descriptions of the various types of reflection.

Information regarding reflections is returned via the two boolean pointers refVert and refHoriz. If the two annuli are identically opposite each other as described by switchSides(), both booleans will be set to `false`. If the two annuli are identically opposite after one undergoes a vertical and/or horizontal reflection, then the booleans refVert and/or refHoriz will be set to `true` accordingly.

The critical difference between this routine and isJoined() is that this routine insists that the fibres on each annulus be consistent. This routine is thus suitable for examining joins between different sections of the same Seifert fibred space, for example.

Python:
  This routine only takes a single argument (the annulus other). The return value is a tuple of three booleans: the usual return value, the value returned in refVert, and the value returned in refHoriz.

Parameters

  other | the annulus to compare with this.
  refVert | returns information on whether the annuli are adjacent modulo a vertical reflection. This is set to `true` if a vertical reflection is required and `false` if it is not. If no adjacency was found at all, this boolean is not touched. A null pointer may be passed, in which case this information will not be returned at all.
  refHoriz | returns information on whether the annuli are adjacent modulo a horizontal reflection. This is set to `true` if a horizontal reflection is required and `false` if it is not. If no adjacency was found at all, this boolean is not touched. A null pointer may be passed, in which case this information will not be returned at all.

Returns
  `true` if some adjacency was found (either with or without reflections), or `false` if no adjacency was found at all.

bool regina::NSatAnnulus::isJoined | ( | const NSatAnnulus & | other,
|  | NMatrix2 & | matching
| ) |  | const

Determines whether this and the given annulus are joined in some form, even if the fibres on each annulus are not consistent.

This routine treats each annulus as though its boundaries are identified to form a torus (though it does not actually test whether this is true). It then examines whether this and the given annulus represent opposite sides of the same torus. More specifically, it tests whether both annuli are formed from the same pair of triangles, and whether the mapping of 0/1/2 markings from one annulus to the other is the same for each triangle. Note that the triangles are allowed to be switched (i.e., the first triangle of one annulus may be the second triangle of the other).

The critical difference between this routine and isAdjacent() is that this routine allows the fibres on each annulus to be inconsistent. This routine is thus suitable for examining joins between different Seifert fibred blocks in a graph manifold, for example.

If the two annuli are joined, the precise relationship between the curves on each annulus will be returned in the matrix matching. Specifically, let x and y be the oriented curves running from markings 0-1 and 0-2 respectively on the first triangle of this annulus. Likewise, let x' and y' run from markings 0-1 and 0-2 respectively on the first triangle of the annulus other. Then the joining between the two annuli can be expressed as follows:

        [x ]                [x']
        [  ]  =  matching * [  ].
        [y ]                [y']

Parameters

  other | the annulus to compare with this.
  matching | returns details on how the curves on each annulus are related. If the this and the given annulus are not joined, then this matrix is not touched.

Returns
  `true` if this and the given annulus are found to be joined, or `false` if they are not.

bool regina::NSatAnnulus::isTwoSidedTorus | ( |  | ) | const

Determines whether this annulus has its boundaries identified to form an embedded two-sided torus within the surrounding triangulation.

It will be verified that:

- the two triangles of this annulus are joined along all three pairs of edges to form a torus;
- the three edges of this torus remain distinct (i.e., different edges of the torus do not become identified within the larger triangulation);
- this torus is two-sided within the surrounding triangulation.

Returns
  `true` if this annulus forms an embedded two-sided torus as described above, or `false` if it does not.

unsigned regina::NSatAnnulus::meetsBoundary | ( |  | ) | const

Determines how many triangles of this annulus lie on the boundary of the triangulation.

Note that this routine can also be used as a boolean function to determine whether any triangles of the annulus lie on the triangulation boundary.

Returns
  the number of triangles of this annulus that lie on the boundary of the triangulation; this will be 0, 1 or 2.

bool regina::NSatAnnulus::operator!= | ( | const NSatAnnulus & | other | ) | const

inline

Determines whether or not this and the given structure describe the same annulus with the same representation.

This requires both structures to have identical tet[] and roles[] arrays.

Parameters

  other | the structure to compare with this.

Returns
  `true` if the structures do not describe the same annulus with the same representation, or `false` if they do.

NSatAnnulus & regina::NSatAnnulus::operator= | ( | const NSatAnnulus & | cloneMe | ) |

inline

Makes this equal to a clone of the given structure.

Parameters

  cloneMe | the structure to clone.

Returns
  a reference to this structure.

bool regina::NSatAnnulus::operator== | ( | const NSatAnnulus & | other | ) | const

inline

Determines whether or not this and the given structure describe the same annulus with the same representation.

This requires both structures to have identical tet[] and roles[] arrays.

Parameters

  other | the structure to compare with this.

Returns
  `true` if the structures describe the same annulus with the same representation, or `false` if they do not.

NSatAnnulus regina::NSatAnnulus::otherSide | ( |  | ) | const

inline

Returns a representation of the same annulus from the other side.

This structure will not be changed. See switchSides() for further details.

Precondition
  Neither triangle of this annulus is a boundary triangle of the triangulation.

Returns
  a new representation of this annulus from the other side.

void regina::NSatAnnulus::reflectHorizontal | ( |  | ) |

inline

Performs a left-to-right reflection of this annulus representation.

The vertical direction of the fibres will remain unchanged, but the first and second triangles will be switched (and the 0..2 markings changed to compensate).

void regina::NSatAnnulus::reflectVertical | ( |  | ) |

inline

Reverses the direction of the vertical fibres in this annulus representation.

The first and second triangles (as described in the class notes) will remain unchanged, but the markings 0 and 1 on each triangle will be switched.

void regina::NSatAnnulus::rotateHalfTurn | ( |  | ) |

inline

Rotates the representation of this annulus by 180 degrees.

This has the effect of switching the first and second triangles and also reversing the direction of the vertical fibres.

Calling this routine is equivalent to calling reflectVertical() and then reflectHorizontal().

void regina::NSatAnnulus::switchSides | ( |  | ) |

Converts this into a representation of the same annulus from the other side.

The first and second triangles and their 0..2 markings (as described in the class notes) remain unchanged. However, the two tetrahedra that are used to describe the annulus will be replaced by their counterparts on the other side of the annulus (i.e., the two new tetrahedra that meet the two original tetrahedra along the annulus itself).

Precondition
  Neither triangle of this annulus is a boundary triangle of the triangulation.

void regina::NSatAnnulus::transform | ( | const NTriangulation * | originalTri,
|  | const NIsomorphism * | iso,
|  | NTriangulation * | newTri
| ) |  |

Adjusts this annulus representation according to the given isomorphism between triangulations.

The given isomorphism must describe a mapping from originalTri to newTri, and this annulus must refer to tetrahedra in originalTri. This routine will adjust this annulus according to the given isomorphism, so that it refers to the corresponding tetrahedra in newTri (with the roles permutations also updated accordingly).

Precondition
  This annulus refers to tetrahedra in originalTri, and iso describes a mapping from originalTri to newTri.

Parameters

  originalTri | the triangulation currently used by this annulus representation.
  iso | the mapping from originalTri to newTri.
  newTri | the triangulation to be used by the updated annulus representation.

NSatAnnulus regina::NSatAnnulus::verticalReflection | ( |  | ) | const

inline

Returns a representation of this annulus in which the vertical direction of the fibres has been reversed.

This structure will not be changed. See reflectVertical() for further details.

Returns
  a new representation of this annulus in which fibres have been reversed.

## Member Data Documentation

NPerm4 regina::NSatAnnulus::roles[2]

Describes how the first and second triangles match up with individual tetrahedron vertices.

See the class notes for details.

NTetrahedron* regina::NSatAnnulus::tet[2]

Describes which tetrahedra provide the first and second triangles.

See the class notes for details.

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

- subcomplex/nsatannulus.h

Copyright © 1999-2014, 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).