regina::NSatRegion Class Reference
Standard Triangulations and Subcomplexes

A large saturated region in a Seifert fibred space formed by joining together saturated blocks. More...

`#include <subcomplex/nsatregion.h>`

Inheritance diagram for regina::NSatRegion:

## Public Member Functions

| NSatRegion (NSatBlock *starter)
| Constructs a new region containing just the given block. More...
virtual | ~NSatRegion ()
| Destroys this structure and all of its internal data, including the individual blocks that make up this region. More...
unsigned long | numberOfBlocks () const
| Returns the number of saturated blocks that come together to form this saturated region. More...
const NSatBlockSpec & | block (unsigned long which) const
| Returns details of the requested saturated block within this region. More...
long | blockIndex (const NSatBlock *block) const
| Returns the index of the given block within this region. More...
unsigned long | numberOfBoundaryAnnuli () const
| Returns the number of saturated annuli that together form the boundary components of this region. More...
const NSatAnnulus & | boundaryAnnulus (unsigned long which, bool &blockRefVert, bool &blockRefHoriz) const
| Returns the requested saturated annulus on the boundary of this region. More...
void | boundaryAnnulus (unsigned long which, NSatBlock *&block, unsigned &annulus, bool &blockRefVert, bool &blockRefHoriz) const
| Returns fine details of the requested saturated annulus on the boundary of this region. More...
NSFSpace * | createSFS (bool reflect) const
| Returns details of the Seifert fibred space represented by this region. More...
NSFSpace * | createSFS (long, bool reflect) const
| A deprecated version of the routine that returns details of the Seifert fibred space represented by this region. More...
bool | expand (NSatBlock::TetList &avoidTets, bool stopIfIncomplete=false)
| Expands this region as far as possible within the overall triangulation. More...
void | writeBlockAbbrs (std::ostream &out, bool tex=false) const
| Writes an abbreviated list of blocks within this region to the given output stream. More...
void | writeDetail (std::ostream &out, const std::string &title) const
| Writes details of the composition of this region to the given output stream. More...
void | writeTextShort (std::ostream &out) const
| Writes this object in short text format to the given output stream. More...
void | writeTextLong (std::ostream &out) const
| Writes this object in long text format to the given output stream. More...
Input and Output
std::string | str () const
| Returns the output from writeTextShort() as a string. More...
std::string | toString () const
| A deprecated alias for str(), which returns the output from writeTextShort() as a string. More...
std::string | detail () const
| Returns the output from writeTextLong() as a string. More...
std::string | toStringLong () const
| A deprecated alias for detail(), which returns the output from writeTextLong() as a string. More...

## Detailed Description

A large saturated region in a Seifert fibred space formed by joining together saturated blocks.

Like a saturated block (described in the class NSatBlock), a saturated region is a connected set of tetrahedra built from a subset of fibres. Unlike a saturated block however, a saturated region has no constraints on its boundary - it may have several boundary components or it may have none. For instance, a saturated region might be an entire closed Seifert fibred space, or it might describe a Seifert fibred component of a JSJ decomposition.

A saturated region is formed from a collection of saturated blocks by joining the boundary annuli of these blocks together in pairs. The joins must be made so that the fibres are consistent, though it is allowable to reverse the directions of the fibres. There is no problem with joining two boundary annuli from the same block to each other.

Any boundary annulus of a block that is not joined to some other boundary annulus of a block becomes a boundary annulus of the entire region. In this way, each boundary component of the region (if there are any at all) is formed from a ring of boundary annuli, in the same way that the boundary of a block is. Note that the routine NSatBlock::nextBoundaryAnnulus() can be used to trace around a region boundary. Like block boundaries, the boundary of a saturated region need not be part of the boundary of the larger triangulation (i.e., there may be adjacent tetrahedra that are not recognised as part of this saturated structure).

The NSatRegion class stores a list of its constituent blocks, but it does not directly store which block boundary annuli are joined to which. This adjacency information is stored within the blocks themselves; see the notes regarding adjacency in the NSatBlock class description.

Blocks cannot be added to a region by hand. The way a region is constructed is by locating some initial block within a triangulation and passing this to the NSatRegion constructor, and then by calling expand() to locate adjacent blocks and expand the region as far as possible. For locating initial blocks, the class NSatBlockStarterSearcher may be of use.

Warning
  It is crucial that the adjacency information stored in the blocks is consistent with the region containing them. All this requires is that the blocks are not manipulated externally (e.g., NSatBlock::setAdjacent() is not called on any of the blocks), but instead all adjacency information is managed by this class. Routines such as expand() which may add more blocks to the region will update the block adjacencies accordingly.

Todo:
  Feature: Have this class track the boundary components properly, with annuli grouped and oriented according to the region boundaries (as opposed to individual block boundaries).

## Constructor & Destructor Documentation

regina::NSatRegion::NSatRegion | ( | NSatBlock * | starter | ) |

Constructs a new region containing just the given block.

All boundary annuli of the given block will become boundary annuli of this region. It is guaranteed that this block will be stored in the region without any kind of reflection (see NSatBlockSpec for details).

Typically a region is initialised using this constructor, and then grown using the expand() routine. For help in finding an initial starter block, see the NSatBlockStarterSearcher class.

This region will claim ownership of the given block, and upon destruction it will destroy this block also.

Precondition
  The given block has no adjacencies listed. That is, for every boundary annulus of the given block, NSatBlock::hasAdjacentBlock() returns `false`.

Parameters

  starter | the single block that this region will describe.

virtual regina::NSatRegion::~NSatRegion | ( |  | ) |

virtual

Destroys this structure and all of its internal data, including the individual blocks that make up this region.

## Member Function Documentation

const NSatBlockSpec & regina::NSatRegion::block | ( | unsigned long | which | ) | const

inline

Returns details of the requested saturated block within this region.

The information will returned will include structural information for the block, along with details of how the block is aligned (e.g., reflected vertically or horizontally) within the larger region.

Parameters

  which | indicates which of the constituent blocks should be returned; this must be between 0 and numberOfBlocks()-1 inclusive.

Returns
  details of the requested saturated block.

long regina::NSatRegion::blockIndex | ( | const NSatBlock * | block | ) | const

Returns the index of the given block within this region.

This index corresponds to the integer parameter that is passed to the routine block().

Warning
  This routine is slow, since it simply scans through the blocks in this region one by one until the given block is found (or until all blocks are exhausted).

Returns
  the index of the given block (as an integer between 0 and numberOfBlocks()-1 inclusive), or -1 if the block is not part of this region.

const NSatAnnulus& regina::NSatRegion::boundaryAnnulus | ( | unsigned long | which,
|  | bool & | blockRefVert,
|  | bool & | blockRefHoriz
| ) |  | const

Returns the requested saturated annulus on the boundary of this region.

The saturated annuli that together form the boundary components of this region are numbered from 0 to numberOfBoundaryAnnuli()-1 inclusive. The argument which specifies which one of these annuli should be returned.

Currently the annuli are numbered lexicographically by block and then by annulus number within the block, although this ordering is subject to change in future versions of Regina. In particular, the annuli are not necessarily numbered in order around the region boundaries, and each region boundary component might not even be given a consecutive range of numbers.

It is guaranteed however that, if the starter block passed to the NSatRegion constructor provides any boundary annuli for the overall region, then the first such annulus in the starter block will be numbered 0 here.

The structure returned will be the annulus precisely as it appears within its particular saturated block. As discussed in the NSatBlockSpec class notes, the block might be reflected horizontally and/or vertically within the overall region, which will affect how the annulus is positioned as part of the overall region boundary (e.g., the annulus might be positioned upside-down in the overall region boundary, or it might be positioned with its second triangle appearing before its first triangle as one walks around the boundary). To account for this, the two boolean arguments blockRefVert and blockRefHoriz will be modified to indicate if and how the block is reflected.

Warning
  This routine is quite slow, since it currently scans through every annulus of every saturated block. Use it sparingly!

Python:
  Both variants of boundaryAnnulus() are combined into a single routine, which takes the integer which as its only argument and returns its results as a tuple. See the alternate version of boundaryAnnulus() for details on how the return tuple is structured.

Parameters

  which | specifies which boundary annulus of this region to return; this must be between 0 and numberOfBoundaryAnnuli()-1 inclusive.
  blockRefVert | used to return whether the block containing the requested annulus is vertically reflected within this region (see NSatBlockSpec for details). This will be set to `true` if the block is vertically reflected, or `false` if not.
  blockRefHoriz | used to return whether the block containing the requested annulus is horizontally reflected within this region (see NSatBlockSpec for details). This will be set to `true` if the block is horizontally reflected, or `false` if not.

Returns
  details of the requested boundary annulus, precisely as it appears within its particular saturated block.

void regina::NSatRegion::boundaryAnnulus | ( | unsigned long | which,
|  | NSatBlock *& | block,
|  | unsigned & | annulus,
|  | bool & | blockRefVert,
|  | bool & | blockRefHoriz
| ) |  | const

Returns fine details of the requested saturated annulus on the boundary of this region.

The argument which specifies which one of these annuli should be returned. See the boundaryAnnulus(unsigned long, bool&, bool&) documentation for details on how the boundary annuli are numbered.

Various details of the requested boundary annulus are returned in the various arguments, as described below.

Be aware that the block containing the requested annulus might be reflected horizontally and/or vertically within the overall region, as discussed in the NSatBlockSpec class notes. This will affect how the annulus is positioned as part of the overall region boundary (e.g., the annulus might be positioned upside-down in the overall region boundary, or it might be positioned with its second triangle appearing before its first triangle as one walks around the boundary). The two boolean arguments blockRefVert and blockRefHoriz will be modified to indicate if and how the block is reflected.

Warning
  This routine is quite slow, since it currently scans through every annulus of every saturated block. Use it sparingly!

Python:
  This routine only takes a single argument (the integer which). The return value is a tuple of four values: the block returned in block, the integer returned in annulus, the boolean returned in blockRefVert, and the boolean returned in blockRefHoriz.

Parameters

  which | specifies which boundary annulus of this region to return; this must be between 0 and numberOfBoundaryAnnuli()-1 inclusive.
  block | used to return the particular saturated block containing the requested annulus.
  annulus | used to return which annulus number in the returned block is the requested annulus; this will be between 0 and block->nAnnuli() inclusive.
  blockRefVert | used to return whether the block containing the requested annulus is vertically reflected within this region (see NSatBlockSpec for details). This will be set to `true` if the block is vertically reflected, or `false` if not.
  blockRefHoriz | used to return whether the block containing the requested annulus is horizontally reflected within this region (see NSatBlockSpec for details). This will be set to `true` if the block is horizontally reflected, or `false` if not.

NSFSpace* regina::NSatRegion::createSFS | ( | bool | reflect | ) | const

Returns details of the Seifert fibred space represented by this region.

Each boundary component of this region will be formed from a ring of saturated annuli, which together form a torus or a Klein bottle. For torus boundary components, the oriented curves representing the fibres and base orbifold on the boundary (see Notation for Seifert fibred spaces) will be as follows.

- Consider the 0/1/2 markings on the first and second triangles of each saturated annulus, as described in the NSatAnnulus class notes.
- The fibres are represented by the oriented edge joining markings 1 and 0 on the first triangle (or 0 and 1 on the second triangle). This is reversed if the block containing the boundary annulus is vertically reflected.
- The curve representing the base orbifold run along the oriented edge joining markings 0 and 2 on the first triangle (or 2 and 0 on the second triangle). This is reversed if the block containing the boundary annulus is horizontally reflected.
- See the NSatBlockSpec overview for descriptions of horizontal and vertical reflection.

If the argument reflect is `true`, the Seifert fibred space will be created as though the entire region had been reflected. In particular, each twist or exceptional fibre will be negated before being added to the Seifert structure.

For Klein bottle boundary components, these curves must (for now) be analysed by hand.

Parameters

  reflect | `true` if this region is to be reflected as the Seifert fibred space is created, or `false` if not.

Returns
  the newly created structure of the underlying Seifert fibred space.

NSFSpace * regina::NSatRegion::createSFS | ( | long | ,
|  | bool | reflect
| ) |  | const

inline

A deprecated version of the routine that returns details of the Seifert fibred space represented by this region.

This is an old and now-deprecated version of createSFS(), which imposed additional preconditions (all boundary components had to be tori), and required the user to pass the number of boundary components as the first argument. This first argument is now ignored, and the preconditions have been relaxed to allow Klein bottle boundary components also.

See createSFS(bool), the new version of this routine, for further details.

Deprecated:
  This routine simply ignores the first argument, and passes the second argument through to createSFS(bool). Code should be changed to call createSFS(bool) directly.

Parameters

  reflect | `true` if this region is to be reflected as the Seifert fibred space is created, or `false` if not.

Returns
  the newly created structure of the underlying Seifert fibred space.

std::string regina::ShareableObject::detail | ( |  | ) | const

inherited

Returns the output from writeTextLong() as a string.

Returns
  a long text representation of this object.

bool regina::NSatRegion::expand | ( | NSatBlock::TetList & | avoidTets,
|  | bool | stopIfIncomplete = `false`
| ) |  |

Expands this region as far as possible within the overall triangulation.

This routine will hunt for new saturated blocks, and will also hunt for new adjacencies between existing blocks.

The first argument to this routine is the tetrahedron list avoidTets. This is a list of tetrahedra that will not be considered when examining potential new blocks. This list will be modified by this routine; in particular, it will be expanded to include all tetrahedra for any new blocks that are found. Before calling this routine it should contain tetrahedra for blocks already in this region, as discussed in the preconditions below.

It may be that you are searching for a region that fills an entire triangulation component (i.e., every boundary annulus of the region in fact forms part of the boundary of the triangulation). In this case you may pass the optional argument stopIfIncomplete as `true`. This means that if this routine ever discovers an annulus that is not part of the triangulation boundary and that it cannot match with some adjacent block, it will exit immediately and return `false`. Note that the region structure will be incomplete and/or inconsistent if this happens; in this case the unfinished region should be destroyed completely and never used.

For internal purposes, it should be noted that any new blocks that are discovered will be added to the end of the internal block list (thus the indices of existing blocks will not change).

Warning
  When joining blocks together, it is possible to create invalid edges (e.g., by joining a one-annulus untwisted boundary to a one-annulus twisted boundary). This routine does not check for such conditions. It is recommended that you run NTriangulation::isValid() before calling this routine.

Precondition
  If any blocks already belonging to this region have adjacencies listed in their NSatBlock structures, then these adjacent blocks belong to this region also. This precondition is easily satisfied if you let the NSatRegion constructor and expand() do all of the adjacency handling, as described in the class notes.
  The list avoidTets includes all tetrahedra on the boundaries of any blocks already contained in this region.

Python:
  The first argument avoidTets is not present. An empty list will be passed instead.

Parameters

  avoidTets | a list of tetrahedra that should not be considered for new blocks, as discussed above. Note that this list may be modified by this routine.
  stopIfIncomplete | `true` if you are filling an entire triangulation component with this region and you wish this routine to exit early if this is not possible, or `false` (the default) if you simply wish to expand this region as far as you can. See above for further discussion.

Returns
  `false` if the optional argument stopIfIncomplete was passed as `true` but expansion did not fill the entire triangulation component as described above, or `true` in all other cases.

unsigned long regina::NSatRegion::numberOfBlocks | ( |  | ) | const

inline

Returns the number of saturated blocks that come together to form this saturated region.

unsigned long regina::NSatRegion::numberOfBoundaryAnnuli | ( |  | ) | const

inline

Returns the number of saturated annuli that together form the boundary components of this region.

Returns
  the number of boundary annuli.

std::string regina::ShareableObject::str | ( |  | ) | const

inherited

Returns the output from writeTextShort() as a string.

Python:
  This implements the `__str__()` function.

Returns
  a short text representation of this object.

std::string regina::ShareableObject::toString | ( |  | ) | const

inline inherited

A deprecated alias for str(), which returns the output from writeTextShort() as a string.

Deprecated:
  This routine has (at long last) been deprecated; use the simpler-to-type str() instead.

Returns
  a short text representation of this object.

std::string regina::ShareableObject::toStringLong | ( |  | ) | const

inline inherited

A deprecated alias for detail(), which returns the output from writeTextLong() as a string.

Deprecated:
  This routine has (at long last) been deprecated; use the simpler-to-type detail() instead.

Returns
  a long text representation of this object.

void regina::NSatRegion::writeBlockAbbrs | ( | std::ostream & | out,
|  | bool | tex = `false`
| ) |  | const

Writes an abbreviated list of blocks within this region to the given output stream.

Blocks will be written using their abbreviated names, and these names will be separated by commas. See NSatBlock::writeAbbr() for further details.

The blocks within this region will be sorted before their abbreviated names are output. The particular method of sorting is an arbitrary aesthetic decision on the part of the author, and is subject to change in future versions of Regina.

Python:
  The parameter out does not exist; standard output will be used.

Parameters

  out | the output stream to which to write.
  tex | `true` if the output should be formatted for TeX, or `false` if it should be written as plain text.

void regina::NSatRegion::writeDetail | ( | std::ostream & | out,
|  | const std::string & | title
| ) |  | const

Writes details of the composition of this region to the given output stream.

The output will consist of several lines. The first line will contain the title string (passed as a separate argument to this routine), followed by a colon. Following this will be a number of lines describing the individual blocks that make up this region and the various adjacencies between them.

Python:
  The parameter out does not exist; standard output will be used.

Parameters

  out | the output stream to which to write.
  title | the name of this region, to be written on the first line of output.

void regina::NSatRegion::writeTextLong | ( | std::ostream & | out | ) | const

inline virtual

Writes this object in long text format to the given output stream.

The output should provide the user with all the information they could want. The output should be human-readable, should not contain extremely long lines (so users can read the output in a terminal), and should end with a final newline.

The default implementation of this routine merely calls writeTextShort() and adds a newline.

Python:
  The parameter out does not exist; standard output will be used.

Parameters

  out | the output stream to which to write.

Reimplemented from regina::ShareableObject.

void regina::NSatRegion::writeTextShort | ( | std::ostream & | out | ) | const

virtual

Writes this object in short text format to the given output stream.

The output should be human-readable, should fit on a single line, and should not end with a newline.

Python:
  The parameter out does not exist; standard output will be used.

Parameters

  out | the output stream to which to write.

Implements regina::ShareableObject.

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

- subcomplex/nsatregion.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).