Regina Calculation Engine
|
A large saturated region in a Seifert fibred space formed by joining together saturated blocks. More...
#include <subcomplex/nsatregion.h>
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... | |
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.
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.
false
.starter | the single block that this region will describe. |
|
virtual |
Destroys this structure and all of its internal data, including the individual blocks that make up this region.
|
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.
which | indicates which of the constituent blocks should be returned; this must be between 0 and numberOfBlocks()-1 inclusive. |
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().
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.
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. |
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.
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.
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.
reflect | true if this region is to be reflected as the Seifert fibred space is created, or false if not. |
|
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.
reflect | true if this region is to be reflected as the Seifert fibred space is created, or false if not. |
|
inherited |
Returns the output from writeTextLong() as a string.
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).
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. |
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.
|
inline |
Returns the number of saturated blocks that come together to form this saturated region.
|
inline |
Returns the number of saturated annuli that together form the boundary components of this region.
|
inherited |
Returns the output from writeTextShort() as a string.
__str__()
function.
|
inlineinherited |
A deprecated alias for str(), which returns the output from writeTextShort() as a string.
|
inlineinherited |
A deprecated alias for detail(), which returns the output from writeTextLong() as a string.
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.
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.
out | the output stream to which to write. |
title | the name of this region, to be written on the first line of output. |
|
inlinevirtual |
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.
out | the output stream to which to write. |
Reimplemented from regina::ShareableObject.
|
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.
out | the output stream to which to write. |
Implements regina::ShareableObject.