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

#include <subcomplex/satregion.h>

Inheritance diagram for regina::SatRegion:

Public Member Functions
	SatRegion (const SatRegion &src)
	Creates a new copy of the given region. More...

	SatRegion (SatRegion &&) noexcept=default
	Moves the contents of the given region into this new region. More...

SatRegion &	operator= (const SatRegion &src)
	Sets this to be a copy of the given region. More...

SatRegion &	operator= (SatRegion &&) noexcept=default
	Moves the contents of the given region into this region. More...

void	swap (SatRegion &other) noexcept
	Swaps the contents of this and the given region. More...

size_t	countBlocks () const
	Returns the number of saturated blocks that come together to form this saturated region. More...

size_t	numberOfBlocks () const
	Deprecated routine that returns the number of saturated blocks in this saturated region. More...

const SatBlockSpec &	block (size_t which) const
	Returns details of the requested saturated block within this region. More...

long	blockIndex (const SatBlock *block) const
	Returns the index of the given block within this region. More...

size_t	countBoundaryAnnuli () const
	Returns the number of saturated annuli that together form the boundary components of this region. More...

size_t	numberOfBoundaryAnnuli () const
	Deprecated routine that returns the number of saturated annuli in the boundary of this region. More...

std::tuple< const SatBlock *, unsigned, bool, bool >	boundaryAnnulus (size_t which) const
	Returns details of the requested saturated annulus on the boundary of this region. More...

bool	operator== (const SatRegion &other) const
	Determines whether this and the given object represent the same combinatorial presentation of a saturated region. More...

bool	operator!= (const SatRegion &other) const
	Determines whether this and the given object represent diffrerent combinatorial presentations of a saturated region. More...

SFSpace	createSFS (bool reflect) const
	Returns details of the Seifert fibred space represented by this region. More...

std::string	blockAbbrs (bool tex=false) const
	Returns an abbreviated list of blocks within this region in string format. 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 a short text representation of this object to the given output stream. More...

void	writeTextLong (std::ostream &out) const
	Writes a detailed text representation of this object to the given output stream. More...

std::string	str () const
	Returns a short text representation of this object. More...

std::string	utf8 () const
	Returns a short text representation of this object using unicode characters. More...

std::string	detail () const
	Returns a detailed text representation of this object. More...

Static Public Member Functions
template<typename Action , typename... Args>
static bool	find (const Triangulation< 3 > &tri, bool mustBeComplete, Action &&action, Args &&... args)
	Runs a search for every isomorphic embedding of every starter block from the global SatBlockStarterSet within the given triangulation. More...

static std::unique_ptr< SatRegion >	beginsRegion (const SatAnnulus &annulus, SatBlock::TetList &avoidTets)
	Determines whether the given annulus is in fact a boundary annulus for a saturated region. 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 SatBlock), 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 SatBlock::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 SatRegion 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 SatBlock class description.

This class implements C++ move semantics and adheres to the C++ Swappable requirement. It is designed to avoid deep copies wherever possible, even when passing or returning objects by value. Note, however, that the only way to create objects of this class (aside from copying or moving) is via the static search functions, such as find() or beginsRegion().

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., SatBlock::setAdjacent() is not called on any of the blocks), but instead all adjacency information is managed by this class.

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

◆ SatRegion() [1/2]

regina::SatRegion::SatRegion ( const SatRegion & src )

Creates a new copy of the given region.

Parameters

src	the region to copy.

◆ SatRegion() [2/2]

regina::SatRegion::SatRegion ( SatRegion && )

defaultnoexcept

Moves the contents of the given region into this new region.

This is a fast (constant time) operation.

The region that was passed will no longer be usable.

Member Function Documentation

◆ beginsRegion()

std::unique_ptr< SatRegion > regina::SatRegion::beginsRegion	(	const SatAnnulus &	annulus,
		SatBlock::TetList &	avoidTets
	)

inlinestatic

Determines whether the given annulus is in fact a boundary annulus for a saturated region.

The annulus should be represented from the inside of the proposed saturated region.

All tetrahedra in the given list avoidTets will be ignored by this routine, and so if a region is found then it is guaranteed not to include any of them. As a consequence, if the given annulus uses any of these tetrahedra then null will be returned.

If a region is found, it will be expanded as far as possible, and all of the tetrahedra within it will be added to the list avoidTets. Moreover, it is guaranteed that the given annulus will be listed as annulus number 0 in the block that contains it, without any horizontal or vertical reflection.

Precondition: Either the given annulus lies on the boundary of the triangulation, or else the (one or two) tetrahedra attached to the other side of it are already in the list avoidTets. This is necessary to ensure that the saturated region does not expand through the annulus to the other side.

Parameters

annulus	the proposed boundary annulus that should form part of the new saturated region.
avoidTets	the list of tetrahedra that should not be considered, and to which any new tetrahedra will be added.

Returns: details of the saturated region if one was found, or null if none was found.

◆ block()

const SatBlockSpec & regina::SatRegion::block ( size_t 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 countBlocks()-1 inclusive.

Returns: details of the requested saturated block.

◆ blockAbbrs()

std::string regina::SatRegion::blockAbbrs ( bool tex = false ) const

inline

Returns an abbreviated list of blocks within this region in string format.

The string that is returned will consist of the abbreviated names of all blocks in this region, separated by commas and spaces. See SatBlock::abbr() 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.

Parameters

tex	`true` if the output should be formatted for TeX, or `false` if it should be written as plain text.

Returns: the abbreviated list of all blocks.

◆ blockIndex()

long regina::SatRegion::blockIndex ( const SatBlock * 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 countBlocks()-1 inclusive), or -1 if the block is not part of this region.

◆ boundaryAnnulus()

std::tuple< const SatBlock *, unsigned, bool, bool > regina::SatRegion::boundaryAnnulus ( size_t which ) const

Returns details of 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 countBoundaryAnnuli()-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 SatRegion constructor provides any boundary annuli for the overall region, then the first such annulus in the starter block will be numbered 0 here.

Be aware that the block containing the requested annulus might be reflected horizontally and/or vertically within the overall region, as discussed in the SatBlockSpec 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). To account for this, the return value will include two booleans refVert and refHoriz 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!

Exceptions

InvalidArgument the argument which was not between 0 and countBoundaryAnnuli()-1 inclusive.

Parameters

which specifies which boundary annulus of this region to return; this must be between 0 and countBoundaryAnnuli()-1 inclusive.

Returns: a tuple (block, annulus, refVert, refHoriz), where: block is a pointer to the the particular saturated block containing the requested annulus; annulus indicates which annulus number in the returned block is the requested annulus, as an integer between 0 and block->countAnnuli()-1 inclusive; refVert is true if and only if the block containing the requested annulus is vertically reflected within this region; and refHoriz is true if and only if the block containing the requested annulus is horizontally reflected within this region. See SatBlockSpec for further details on these reflections.

◆ countBlocks()

size_t regina::SatRegion::countBlocks ( ) const

inline

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

Returns: the total number of blocks.

◆ countBoundaryAnnuli()

size_t regina::SatRegion::countBoundaryAnnuli ( ) const

inline

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

Returns: the number of boundary annuli.

◆ createSFS()

SFSpace regina::SatRegion::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 SatAnnulus 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 SatBlockSpec 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.

There are situations in which Regina is not (yet) capable of determining the Seifert fibred space precisely. This can only happen if the Seifert fibred space is closed, non-orientable, belongs to the class n3 or n4, and has sufficiently large base orbifold genus. In such situations this routine will throw an exception.

Exceptions

NotImplemented This is one of the closed non-orientable cases where Regina cannot distinguish between classes n3 and n4, as described above.

Parameters

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

Returns: the structure of the underlying Seifert fibred space.

◆ detail()

std::string regina::Output< SatRegion , false >::detail ( ) const

inherited

Returns a detailed text representation of this object.

This text may span many lines, and should provide the user with all the information they could want. It should be human-readable, should not contain extremely long lines (which cause problems for users reading the output in a terminal), and should end with a final newline. There are no restrictions on the underlying character set.

Returns: a detailed text representation of this object.

◆ find()

template<typename Action , typename... Args>

static bool regina::SatRegion::find	(	const Triangulation< 3 > &	tri,
		bool	mustBeComplete,
		Action &&	action,
		Args &&...	args
	)

static

Runs a search for every isomorphic embedding of every starter block from the global SatBlockStarterSet within the given triangulation.

Each time an embedding of a starter block is discovered, the block will be wrapped in a new SatRegion which describes how the block appears within the given triangulation. The region will be expanded to encompass as many saturated blocks as possible, and then passed to action, which must be a function or some other callable object.

The first argument to action must be of type std::unique_ptr<SatRegion>; this will be the newly constructed and expanded region that contains the starter block that was found. As expected from std::unique_ptr, this function will have relinquished all ownership of the region, and your action can do what it likes with it.
The second argument to action must be of type SatBlock::TetList&. This list will contain all tetrahedra currently used by the region, and action is welcome to modify the list as it pleases. This function will clear and reuse the list after action returns.
If there are any additional arguments supplied in the list args, then these will be passed as subsequent arguments to action.
action must return a bool. A return value of false indicates that the search for starter blocks should continue, and a return value of true indicates that the search should terminate immediately.

Note that different embeddings of the same starter block within tri will result in the action being called multiple times (with different containing regions).

If 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), then you should pass mustBeComplete as true. If a region expansion does not fill the entire component, then it will be discarded and action will not be called for that particular embeddeding of that particular starter block.

Headers: The implementation of this template function is contained in a separate header (satregion-impl.h), which is not included automatically by this file. If you wish to use this function in your own code, you will need to include satregion-impl.h.

Python: This function is available, and action may be a pure Python function. However, action must take only one argument: the newly constructed SatRegion (i.e., the first argument in the description above). The SatBlock::TetList& argument will not be passed, and there can be no additional argument list args.

Parameters

tri	the triangulation in which to search for starter blocks.
mustBeComplete	`true` if you are searching for a region that fills an entire triangulation component, as described above.
action	a function (or other callable object) to call for each embedding of a starter block that is found.
args	any additional arguments that should be passed to action, following the initial region and tetrahedron list arguments.

Returns: true if action ever terminated the search by returning true, or false if the search was allowed to run to completion.

◆ numberOfBlocks()

size_t regina::SatRegion::numberOfBlocks ( ) const

inline

Deprecated routine that returns the number of saturated blocks in this saturated region.

Deprecated:: This routine has been renamed countBlocks().

Returns: the total number of blocks.

◆ numberOfBoundaryAnnuli()

size_t regina::SatRegion::numberOfBoundaryAnnuli ( ) const

inline

Deprecated routine that returns the number of saturated annuli in the boundary of this region.

Deprecated:: This routine has been renamed countBoundaryAnnuli().

Returns: the total number of boundary annuli.

◆ operator!=()

bool regina::SatRegion::operator!= ( const SatRegion & other ) const

inline

Determines whether this and the given object represent diffrerent combinatorial presentations of a saturated region.

Specifically, in order to compare as equal, two saturated regions must be formed from saturated blocks with the same combinatorial parameters (as returned by the SatBlock comparison operators), and these blocks must be presented in the same order with the same horizontal/vertical reflections and joined together in the same way.

Like the comparison operators for most parameterised subclasses of StandardTriangulation, it does not matter how the constituent tetrahedra and/or their vertices are numbered. However, this test is more specific than combinatorial isomorphism of the underlying subcomplex of the triangulation, since it does not account for the many symmetries in how the same saturated region can be presented.

Parameters

other the saturated region to compare with this.

Returns: true if and only if this and the given object represent different combinatorial presentations of a saturated region.

◆ operator=() [1/2]

SatRegion & regina::SatRegion::operator= ( const SatRegion & src )

inline

Sets this to be a copy of the given region.

Parameters

src	the region to copy.

Returns: a reference to this region.

◆ operator=() [2/2]

SatRegion & regina::SatRegion::operator= ( SatRegion && )

defaultnoexcept

Moves the contents of the given region into this region.

This is a fast (constant time) operation.

The region that was passed will no longer be usable.

Returns: a reference to this region.

◆ operator==()

bool regina::SatRegion::operator== ( const SatRegion & other ) const

Determines whether this and the given object represent the same combinatorial presentation of a saturated region.

Specifically, in order to compare as equal, two saturated regions must be formed from saturated blocks with the same combinatorial parameters (as returned by the SatBlock comparison operators), and these blocks must be presented in the same order with the same horizontal/vertical reflections and joined together in the same way.

Like the comparison operators for most parameterised subclasses of StandardTriangulation, it does not matter how the constituent tetrahedra and/or their vertices are numbered. However, this test is more specific than combinatorial isomorphism of the underlying subcomplex of the triangulation, since it does not account for the many symmetries in how the same saturated region can be presented.

Parameters

other the saturated region to compare with this.

Returns: true if and only if this and the given object represent the same combinatorial presentation of a saturated region.

◆ str()

std::string regina::Output< SatRegion , false >::str ( ) const

inherited

Returns a short text representation of this object.

This text should be human-readable, should use plain ASCII characters where possible, and should not contain any newlines.

Within these limits, this short text ouptut should be as information-rich as possible, since in most cases this forms the basis for the Python str() and repr() functions.

Python: The Python "stringification" function str() will use precisely this function, and for most classes the Python repr() function will incorporate this into its output.

Returns: a short text representation of this object.

◆ swap()

void regina::SatRegion::swap ( SatRegion & other )

inlinenoexcept

Swaps the contents of this and the given region.

Parameters

other the region whose contents should be swapped with this.

◆ utf8()

std::string regina::Output< SatRegion , false >::utf8 ( ) const

inherited

Returns a short text representation of this object using unicode characters.

Like str(), this text should be human-readable, should not contain any newlines, and (within these constraints) should be as information-rich as is reasonable.

Unlike str(), this function may use unicode characters to make the output more pleasant to read. The string that is returned will be encoded in UTF-8.

Returns: a short text representation of this object.

◆ writeBlockAbbrs()

void regina::SatRegion::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 and spaces. See SatBlock::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: Not present; instead use the variant blockAbbrs() that returns a string.

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.

◆ writeDetail()

void regina::SatRegion::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: Not present; instead use detail(), which returns the same detailed information in string form (but without the option of using a custom title).

Parameters

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

◆ writeTextLong()

void regina::SatRegion::writeTextLong ( std::ostream & out ) const

inline

Writes a detailed text representation of this object to the given output stream.

Python: Not present; use detail() instead.

Parameters

out	the output stream to which to write.

◆ writeTextShort()

void regina::SatRegion::writeTextShort ( std::ostream & out ) const

Writes a short text representation of this object to the given output stream.

Python: Not present; use str() instead.

Parameters

out	the output stream to which to write.

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

subcomplex/satregion.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SatRegion() [1/2]

◆ SatRegion() [2/2]

Member Function Documentation

◆ beginsRegion()

◆ block()

◆ blockAbbrs()

◆ blockIndex()

◆ boundaryAnnulus()

◆ countBlocks()

◆ countBoundaryAnnuli()

◆ createSFS()

◆ detail()

◆ find()

◆ numberOfBlocks()

◆ numberOfBoundaryAnnuli()

◆ operator!=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ str()

◆ swap()

◆ utf8()

◆ writeBlockAbbrs()

◆ writeDetail()

◆ writeTextLong()

◆ writeTextShort()