Represents the dual graph of a 3-manifold triangulation. More...

#include <triangulation/facetpairing3.h>

Inheritance diagram for regina::FacetPairing< 3 >:

Public Types
using	IsoList = std::list< Isomorphism< dim > >
	A list of isomorphisms on facet pairings. More...

Public Member Functions
	FacetPairing (const FacetPairing &src)=default
	Creates a new copy of the given face pairing. More...

	FacetPairing (FacetPairing &&src) noexcept=default
	Moves the given face pairing into this face pairing. More...

	FacetPairing (const Triangulation< 3 > &tri)
	Creates the face pairing of the given 3-manifold triangulation. More...

	FacetPairing (std::istream &in)
	Reads a new facet pairing from the given input stream. More...

FacetPairing &	operator= (const FacetPairing &src)=default
	Copies the given face pairing into this face pairing. More...

FacetPairing &	operator= (FacetPairing &&src) noexcept=default
	Moves the given face pairing into this facet pairing. More...

void	followChain (size_t &tet, FacePair &faces) const
	Follows a chain as far as possible from the given point. More...

bool	hasTripleEdge () const
	Determines whether this face pairing contains a triple edge. More...

bool	hasBrokenDoubleEndedChain () const
	Determines whether this face pairing contains a broken double-ended chain. More...

bool	hasOneEndedChainWithDoubleHandle () const
	Determines whether this face pairing contains a one-ended chain with a double handle. More...

bool	hasWedgedDoubleEndedChain () const
	Determines whether this face pairing contains a wedged double-ended chain. More...

bool	hasOneEndedChainWithStrayBigon () const
	Determines whether this face pairing contains a one-ended chain with a stray bigon. More...

bool	hasTripleOneEndedChain () const
	Determines whether this face pairing contains a triple one-ended chain. More...

bool	hasSingleStar () const
	Determines whether this face pairing contains a single-edged star. More...

bool	hasDoubleStar () const
	Determines whether this face pairing contains a double-edged star. More...

bool	hasDoubleSquare () const
	Determines whether this face pairing contains a double-edged square. More...

void	writeTextLong (std::ostream &out) const
	A default implementation for detailed output. 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...

Constructors, Destructors and Assignment
void	swap (FacetPairingBase &other) noexcept
	Swaps the contents of this and the given facet pairing. More...

Basic Queries
size_t	size () const
	Returns the number of simplices whose facets are described by this facet pairing. More...

const FacetSpec< dim > &	dest (const FacetSpec< dim > &source) const
	Returns the other facet to which the given simplex facet is paired. More...

const FacetSpec< dim > &	dest (size_t simp, unsigned facet) const
	Returns the other facet to which the given simplex facet is paired. More...

const FacetSpec< dim > &	operator[] (const FacetSpec< dim > &source) const
	Returns the other facet to which the given simplex facet is paired. More...

bool	isUnmatched (const FacetSpec< dim > &source) const
	Determines whether the given simplex facet has been left deliberately unmatched. More...

bool	isUnmatched (size_t simp, unsigned facet) const
	Determines whether the given simplex facet has been left deliberately unmatched. More...

bool	isClosed () const
	Determines whether this facet pairing is closed. More...

bool	operator== (const FacetPairing< dim > &other) const
	Determines if this and the given facet pairing are identical. More...

bool	operator!= (const FacetPairing< dim > &other) const
	Determines if this and the given facet pairing are not identical. More...

Isomorphic Representations
bool	isCanonical () const
	Determines whether this facet pairing is in canonical form, i.e., is a lexicographically minimal representative of its isomorphism class. More...

IsoList	findAutomorphisms () const
	Returns the set of all combinatorial automorphisms of this facet pairing. More...

Protected Attributes
size_t	size_
	The number of simplices under consideration. More...

FacetSpec< dim > *	pairs_
	The other facet to which each simplex facet is paired. More...

Friends
class	detail::FacetPairingBase< 3 >

Input and Output
void	writeTextShort (std::ostream &out) const
	Writes a human-readable representation of this facet pairing to the given output stream. More...

std::string	toTextRep () const
	Returns a text-based representation of this facet pairing that can be used to reconstruct the facet pairing. More...

void	writeDot (std::ostream &out, const char *prefix=nullptr, bool subgraph=false, bool labels=false) const
	Writes the graph corresponding to this facet pairing in the Graphviz DOT language. More...

std::string	dot (const char *prefix=nullptr, bool subgraph=false, bool labels=false) const
	Returns a Graphviz DOT representation of the graph that describes this facet pairing. More...

FacetSpec< dim > &	dest (const FacetSpec< dim > &source)
	Returns the other facet to which the given simplex facet is paired. More...

FacetSpec< dim > &	dest (size_t simp, unsigned facet)
	Returns the other facet to which the given simplex facet is paired. More...

FacetSpec< dim > &	operator[] (const FacetSpec< dim > &source)
	Returns the other facet to which the given simplex facet is paired. More...

bool	noDest (const FacetSpec< dim > &source) const
	Determines whether the matching for the given simplex facet has not yet been determined. More...

bool	noDest (size_t simp, unsigned facet) const
	Determines whether the matching for the given simplex facet has not yet been determined. More...

bool	isCanonicalInternal (IsoList &list) const
	Determines whether this facet pairing is in canonical (smallest lexicographical) form, given a small set of assumptions. More...

static FacetPairing< dim >	fromTextRep (const std::string &rep)
	Reconstructs a facet pairing from a text-based representation. More...

static void	writeDotHeader (std::ostream &out, const char *graphName=nullptr)
	Writes header information for a Graphviz DOT file that will describe the graphs for one or more facet pairings. More...

static std::string	dotHeader (const char *graphName=nullptr)
	Returns header information for a Graphviz DOT file that will describe the graphs for one or more facet pairings. More...

static void	findAllPairings (size_t nSimplices, BoolSet boundary, int nBdryFacets, Action &&action, Args &&... args)
	Generates all possible facet pairings satisfying the given constraints. More...

Detailed Description

Represents the dual graph of a 3-manifold triangulation.

This is a specialisation of the generic FacetPairing class template; see the FacetPairing documentation for an overview of how this class works.

This 3-dimensional specialisation contains some extra functionality. In particular, it provides routines for finding informative subgraphs within the dual graph.

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.

Member Typedef Documentation

◆ IsoList

using regina::detail::FacetPairingBase< dim >::IsoList = std::list<Isomorphism<dim> >

inherited

A list of isomorphisms on facet pairings.

Such an isomorphism can be used to convert one facet pairing into another.

This type is used to store all automorphisms of a facet pairing; that is, all isomorphisms that map the facet pairing to itself.

Constructor & Destructor Documentation

◆ FacetPairing() [1/4]

regina::FacetPairing< 3 >::FacetPairing ( const FacetPairing< 3 > & src )

default

Creates a new copy of the given face pairing.

Parameters

src	the face pairing to clone.

◆ FacetPairing() [2/4]

regina::FacetPairing< 3 >::FacetPairing ( FacetPairing< 3 > && src )

defaultnoexcept

Moves the given face pairing into this face pairing.

This is a fast (constant time) operation.

The face pairing that is passed (src) will no longer be usable.

Parameters

src	the face pairing to move.

◆ FacetPairing() [3/4]

regina::FacetPairing< 3 >::FacetPairing ( const Triangulation< 3 > & tri )

inline

Creates the face pairing of the given 3-manifold triangulation.

This describes how the tetrahedron faces of the given triangulation are joined together in pairs.

Precondition: The given triangulation is not empty.

Parameters

tri	the triangulation whose face pairing should be constructed.

◆ FacetPairing() [4/4]

regina::FacetPairing< 3 >::FacetPairing ( std::istream & in )

inline

Reads a new facet pairing from the given input stream.

This routine reads data in the format written by toTextRep().

This routine will skip any initial whitespace in the given input stream. Once it finds its first non-whitespace character, it will read the entire line from the input stream and expect that line to containin the text representation of a facet pairing.

If the data found in the input stream is invalid, incomplete or incorrectly formatted, this constructor will throw an InvalidInput exception.

Python: Not present; instead you can use fromTextRep(), which reads this same text format in string form. The main differences between this constructor and fromTextRep() are: (i) fromTextRep() does not skip over initial whitespace; and (ii) fromTextRep() throws InvalidArgument exceptions on error (not InvalidInput).

Parameters

in	the input stream from which to read.

Member Function Documentation

◆ dest() [1/4]

FacetSpec< dim > & regina::detail::FacetPairingBase< dim >::dest ( const FacetSpec< dim > & source )

inlineprotectedinherited

Returns the other facet to which the given simplex facet is paired.

If the given facet is left deliberately unmatched, the value returned will be boundary (as returned by FacetSpec<dim>::isBoundary()).

Precondition: The given facet is a real simplex facet (not boundary, before-the-start or past-the-end).

Parameters

source the facet under investigation.

Returns: the other facet to which the given facet is paired.

◆ dest() [2/4]

const FacetSpec< dim > & regina::detail::FacetPairingBase< dim >::dest ( const FacetSpec< dim > & source ) const

inlineinherited

Returns the other facet to which the given simplex facet is paired.

If the given facet is left deliberately unmatched, the value returned will be boundary (as returned by FacetSpec<dim>::isBoundary()).

Precondition: The given facet is a real simplex facet (not boundary, before-the-start or past-the-end).

Python: This routine returns by value, not by reference, since Python cannot enforce constness otherwise.

Parameters

source the facet under investigation.

Returns: the other facet to which the given facet is paired.

◆ dest() [3/4]

FacetSpec< dim > & regina::detail::FacetPairingBase< dim >::dest	(	size_t	simp,
		unsigned	facet
	)

inlineprotectedinherited

Returns the other facet to which the given simplex facet is paired.

If the given facet is left deliberately unmatched, the value returned will be boundary (as returned by FacetSpec<dim>::isBoundary()).

Parameters

simp	the simplex under investigation (this must be strictly less than the total number of simplices under consideration).
facet	the facet of the given simplex under investigation (between 0 and dim inclusive).

Returns: the other facet to which the given facet is paired.

◆ dest() [4/4]

const FacetSpec< dim > & regina::detail::FacetPairingBase< dim >::dest	(	size_t	simp,
		unsigned	facet
	)		const

inlineinherited

Returns the other facet to which the given simplex facet is paired.

If the given facet is left deliberately unmatched, the value returned will be boundary (as returned by FacetSpec<dim>::isBoundary()).

Python: This routine returns by value, not by reference, since Python cannot enforce constness otherwise.

Parameters

simp	the simplex under investigation (this must be strictly less than the total number of simplices under consideration).
facet	the facet of the given simplex under investigation (between 0 and dim inclusive).

Returns: the other facet to which the given facet is paired.

◆ detail()

template<class T , bool supportsUtf8 = false>

std::string regina::Output< T, supportsUtf8 >::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.

◆ dot()

std::string regina::detail::FacetPairingBase< dim >::dot	(	const char *	prefix = `nullptr`,
		bool	subgraph = `false`,
		bool	labels = `false`
	)		const

inherited

Returns a Graphviz DOT representation of the graph that describes this facet pairing.

This routine simply returns the output of writeDot() as a string, instead of dumping it to an output stream.

All arguments are the same as for writeDot(); see the writeDot() notes for further details.

Returns: the output of writeDot(), as outlined above.

◆ dotHeader()

static std::string regina::detail::FacetPairingBase< dim >::dotHeader ( const char * graphName = nullptr )

staticinherited

Returns header information for a Graphviz DOT file that will describe the graphs for one or more facet pairings.

This routine simply returns the output of writeDotHeader() as a string, instead of dumping it to an output stream.

All arguments are the same as for writeDotHeader(); see the writeDotHeader() notes for further details.

Returns: the output of writeDotHeader(), as outlined above.

◆ findAllPairings()

void regina::detail::FacetPairingBase< dim >::findAllPairings	(	size_t	nSimplices,
		BoolSet	boundary,
		int	nBdryFacets,
		Action &&	action,
		Args &&...	args
	)

inlinestaticinherited

Generates all possible facet pairings satisfying the given constraints.

Only connected facet pairings (pairings in which each simplex can be reached from each other via a series of individual matched facets) will be produced.

Each facet pairing will be produced precisely once up to isomorphism. Facet pairings are considered isomorphic if they are related by a relabelling of the simplices and/or a renumbering of the (dim + 1) facets of each simplex. Each facet pairing that is generated will be a lexicographically minimal representative of its isomorphism class, i.e., will be in canonical form as described by isCanonical().

For each facet pairing that is generated, this routine will call action (which must be a function or some other callable object).

The first argument to action must be a const reference to a FacetPairing<dim>. This will be the facet pairing that was found. If action wishes to keep the facet pairing, it should take a deep copy (not a reference), since the facet pairing may be changed and reused after action returns.
The second argument to action must be a FacetPairing<dim>::IsoList (this will be passed by value using move semantics). This will be the list of all automorphisms of the facet pairing that was found.
If there are any additional arguments supplied in the list args, then these will be passed as subsequent arguments to action.
action must return void.

Because this class cannot represent an empty facet pairing, if the argument nSimplices is zero then no facet pairings will be generated at all.

Todo:

Optimise (long-term): When generating facet pairings, do some checking to eliminate cases in which simplex (k > 0) can be swapped with simplex 0 to produce a smaller representation of the same pairing.

Feature: Allow cancellation of facet pairing generation.

Python: This function is available, and action may be a pure Python function. However, action cannot take any additional arguments beyond the facet pairing and its automorphisms (and therefore the additional args list is omitted here).

Parameters

nSimplices	the number of simplices whose facets should be (potentially) matched.
boundary	determines whether any facets may be left unmatched. This set should contain `true` if pairings with at least one unmatched facet are to be generated, and should contain `false` if pairings with no unmatched facets are to be generated.
nBdryFacets	specifies the precise number of facets that should be left unmatched. If this parameter is negative, it is ignored and no additional restriction is imposed. If parameter boundary does not contain `true`, this parameter is likewise ignored. If parameter boundary does contain true and this parameter is non-negative, only pairings with precisely this many unmatched facets will be generated. In particular, if this parameter is positive then pairings with no unmatched facets will not be produced irrespective of whether `false` is contained in parameter boundary. Note that, in order to produce any pairings at all, this parameter must be of the same parity as `nSimplices * (dim+1)`, and can be at most `(dim-1) * nSimplices + 2`.
action	a function (or other callable object) to call for each facet pairing that is found.
args	any additional arguments that should be passed to action, following the initial facet pairing and automorphism arguments.

◆ findAutomorphisms()

FacetPairingBase< dim >::IsoList regina::detail::FacetPairingBase< dim >::findAutomorphisms

inlineinherited

Returns the set of all combinatorial automorphisms of this facet pairing.

An automorphism is a relabelling of the simplices and/or a renumbering of the (dim + 1) facets of each simplex resulting in precisely the same facet pairing.

This routine uses optimisations that can cause unpredictable breakages if this facet pairing is not in canonical form.

Precondition: This facet pairing is connected, i.e., it is possible to reach any simplex from any other simplex via a series of matched facet pairs.; This facet pairing is in canonical form as described by isCanonical().

Returns: the list of all automorphisms.

◆ followChain()

void regina::FacetPairing< 3 >::followChain	(	size_t &	tet,
		FacePair &	faces
	)		const

Follows a chain as far as possible from the given point.

A chain is the underlying face pairing for a layered chain; specifically it involves one tetrahedron joined to a second along two faces, the remaining two faces of the second tetrahedron joined to a third and so on. A chain can involve as few as one tetrahedron or as many as we like. Note that the remaining two faces of the first tetrahedron and the remaining two faces of the final tetrahedron remain unaccounted for by this structure.

This routine begins with two faces of a given tetrahedron, described by parameters tet and faces. If these two faces are both joined to some different tetrahedron, parameter tet will be changed to this new tetrahedron and parameter faces will be changed to the remaining faces of this new tetrahedron (i.e., the two faces that were not joined to the original faces of the original tetrahedron).

This procedure is repeated as far as possible until either the two faces in question join to two different tetrahedra, the two faces join to each other, or at least one of the two faces is unmatched.

Thus, given one end of a chain, this procedure can be used to follow the face pairings through to the other end of the chain.

Warning: You must be sure when calling this routine that you are not inside a chain that loops back onto itself! If the face pairing forms a large loop with each tetrahedron joined by two faces to the next, this routine will cycle around the loop forever and never return.

Parameters

tet	the index in the underlying triangulation of the tetrahedron to begin at. This parameter will be modified directly by this routine as a way of returning the results.
faces	the pair of face numbers in the given tetrahedron at which we begin. This parameter will also be modified directly by this routine as a way of returning results.

◆ fromTextRep()

static FacetPairing< dim > regina::detail::FacetPairingBase< dim >::fromTextRep ( const std::string & rep )

staticinherited

Reconstructs a facet pairing from a text-based representation.

This text-based representation must be in the format produced by routine toTextRep().

Exceptions

InvalidArgument the given string was not a valid text-based representation of a facet pairing on a positive number of simplices.

Parameters

rep	a text-based representation of a facet pairing, as produced by routine toTextRep().

Returns: the corresponding facet pairing.

◆ hasBrokenDoubleEndedChain()

bool regina::FacetPairing< 3 >::hasBrokenDoubleEndedChain ( ) const

Determines whether this face pairing contains a broken double-ended chain.

A chain involves a sequence of tetrahedra, each joined to the next along two faces, and is described in detail in the documentation for followChain().

A one-ended chain is a chain in which the first tetrahedron is also joined to itself along one face (i.e., the underlying face pairing for a layered solid torus). A double-ended chain is a chain in which the first tetrahedron is joined to itself along one face and the final tetrahedron is also joined to itself along one face (i.e., the underlying face pairing for a layered lens space).

A broken double-ended chain consists of two one-ended chains (using distinct sets of tetrahedra) joined together along one face. The remaining two faces (one from each chain) that were unaccounted for by the individual one-ended chains remain unaccounted for by this broken double-ended chain.

In this routine we are interested specifically in finding a broken double-ended chain that is not a part of a complete double-ended chain, i.e., the final two unaccounted faces are not joined together.

A face pairing containing a broken double-ended chain cannot model a closed minimal irreducible P^2-irreducible 3-manifold triangulation on more than two tetrahedra. See "Face pairing graphs and 3-manifold enumeration", Benjamin A. Burton, J. Knot Theory Ramifications 13 (2004), 1057–1101.

Returns: true if and only if this face pairing contains a broken double-ended chain that is not part of a complete double-ended chain.

◆ hasDoubleSquare()

bool regina::FacetPairing< 3 >::hasDoubleSquare ( ) const

Determines whether this face pairing contains a double-edged square.

A double-edged square involves four distinct tetrahedra that meet each other as follows. Two pairs of tetrahedra are joined along two pairs of faces each. Then each tetrahedron is joined along a single face to one tetrahedron of the other pair. The four tetrahedron faces not yet joined to anything (one from each tetrahedron) remain unaccounted for by this structure.

Returns: true if and only if this face pairing contains a double-edged square.

◆ hasDoubleStar()

bool regina::FacetPairing< 3 >::hasDoubleStar ( ) const

Determines whether this face pairing contains a double-edged star.

A double-edged star involves two tetrahedra that are adjacent along two separate pairs of faces, where the four remaining faces of these tetrahedra are joined to four entirely new tetrahedra (so that none of the six tetrahedra described in this structure are the same).

Returns: true if and only if this face pairing contains a double-edged star.

◆ hasOneEndedChainWithDoubleHandle()

bool regina::FacetPairing< 3 >::hasOneEndedChainWithDoubleHandle ( ) const

Determines whether this face pairing contains a one-ended chain with a double handle.

A chain involves a sequence of tetrahedra, each joined to the next along two faces, and is described in detail in the documentation for followChain().

A one-ended chain is a chain in which the first tetrahedron is also joined to itself along one face (i.e., the underlying face pairing for a layered solid torus).

A one-ended chain with a double handle begins with a one-ended chain. The two faces that are unaccounted for by this one-ended chain must be joined to two different tetrahedra, and these two tetrahedra must be joined to each other along two faces. The remaining two faces of these two tetrahedra remain unaccounted for by this structure.

A face pairing containing a one-ended chain with a double handle cannot model a closed minimal irreducible P^2-irreducible 3-manifold triangulation on more than two tetrahedra. See "Face pairing graphs and 3-manifold enumeration", Benjamin A. Burton, J. Knot Theory Ramifications 13 (2004), 1057–1101.

Returns: true if and only if this face pairing contains a one-ended chain with a double handle.

◆ hasOneEndedChainWithStrayBigon()

bool regina::FacetPairing< 3 >::hasOneEndedChainWithStrayBigon ( ) const

Determines whether this face pairing contains a one-ended chain with a stray bigon.

A chain involves a sequence of tetrahedra, each joined to the next along two faces, and is described in detail in the documentation for followChain().

A one-ended chain is a chain in which the first tetrahedron is also joined to itself along one face (i.e., the underlying face pairing for a layered solid torus).

A one-ended chain with a stray bigon describes the following structure. We begin with a one-ended chain. Two new tetrahedra are added; these are joined to each other along two pairs of faces, and one of the new tetrahedra is joined to the end of the one-ended chain. We then ensure that:

This configuration is not part of a longer one-ended chain that encompasses all of the aforementioned tetrahedra;
There is no extra tetrahedron that is joined to both the two new tetrahedra and the end of the chain;
There is no extra tetrahedron that is joined to the end of the chain along one face and the far new tetrahedron along two additional faces (where by "the far new tetrahedron" we mean the new tetrahedron that was not originally joined to the chain).

Aside from these constraints, the remaining four tetrahedron faces (two faces of the far new tetrahedron, one face of the other new tetrahedron, and one face at the end of the chain) remain unaccounted for by this structure.

A face pairing containing a structure of this type cannot model a closed minimal irreducible P^2-irreducible 3-manifold triangulation on more than two tetrahedra. See "Enumeration of non-orientable 3-manifolds using face-pairing graphs and union-find", Benjamin A. Burton, Discrete Comput. Geom. 38 (2007), no. 3, 527–571.

Returns: true if and only if this face pairing contains a one-ended chain with a stray bigon.

◆ hasSingleStar()

bool regina::FacetPairing< 3 >::hasSingleStar ( ) const

Determines whether this face pairing contains a single-edged star.

A single-edged star involves two tetrahedra that are adjacent along a single face, where the six remaining faces of these tetrahedra are joined to six entirely new tetrahedra (so that none of the eight tetrahedra described in this structure are the same).

Returns: true if and only if this face pairing contains a single-edged star.

◆ hasTripleEdge()

bool regina::FacetPairing< 3 >::hasTripleEdge ( ) const

Determines whether this face pairing contains a triple edge.

A triple edge is where two different tetrahedra are joined along three of their faces.

A face pairing containing a triple edge cannot model a closed minimal irreducible P^2-irreducible 3-manifold triangulation on more than two tetrahedra. See "Face pairing graphs and 3-manifold enumeration", Benjamin A. Burton, J. Knot Theory Ramifications 13 (2004), 1057–1101.

Returns: true if and only if this face pairing contains a triple edge.

◆ hasTripleOneEndedChain()

bool regina::FacetPairing< 3 >::hasTripleOneEndedChain ( ) const

Determines whether this face pairing contains a triple one-ended chain.

A chain involves a sequence of tetrahedra, each joined to the next along two faces, and is described in detail in the documentation for followChain().

A one-ended chain is a chain in which the first tetrahedron is also joined to itself along one face (i.e., the underlying face pairing for a layered solid torus).

A triple one-ended chain is created from three one-ended chains as follows. Two new tetrahedra are added, and each one-ended chain is joined to each of the new tetrahedra along a single face. The remaining two faces (one from each of the new tetrahedra) remain unaccounted for by this structure.

A face pairing containing a triple one-ended chain cannot model a closed minimal irreducible P^2-irreducible 3-manifold triangulation on more than two tetrahedra. See "Enumeration of non-orientable 3-manifolds using face-pairing graphs and union-find", Benjamin A. Burton, Discrete Comput. Geom. 38 (2007), no. 3, 527–571.

Returns: true if and only if this face pairing contains a triple one-ended chain.

◆ hasWedgedDoubleEndedChain()

bool regina::FacetPairing< 3 >::hasWedgedDoubleEndedChain ( ) const

Determines whether this face pairing contains a wedged double-ended chain.

A chain involves a sequence of tetrahedra, each joined to the next along two faces, and is described in detail in the documentation for followChain().

A one-ended chain is a chain in which the first tetrahedron is also joined to itself along one face (i.e., the underlying face pairing for a layered solid torus). A double-ended chain is a chain in which the first tetrahedron is joined to itself along one face and the final tetrahedron is also joined to itself along one face (i.e., the underlying face pairing for a layered lens space).

A wedged double-ended chain is created from two one-ended chains as follows. Two new tetrahedra are added, and each one-ended chain is joined to each of the new tetrahedra along a single face. In addition, the two new tetrahedra are joined to each other along a single face. The remaining two faces (one from each of the new tetrahedra) remain unaccounted for by this structure.

An alternative way of viewing a wedged double-ended chain is as an ordinary double-ended chain, where one of the internal tetrahedra is removed and replaced with a pair of tetrahedra joined to each other. Whereas the original tetrahedron met its two neighbouring tetrahedra along two faces each (giving a total of four face identifications), the two new tetrahedra now meet each of the two neighbouring tetrahedra along a single face each (again giving four face identifications).

Note that if this alternate construction is used to replace one of the end tetrahedra of the double-ended chain (not an internal tetrahedron), the resulting structure will either be a triple edge or a one-ended chain with a double handle (according to whether the original chain has zero or positive length). See hasTripleEdge() and hasOneEndedChainWithDoubleHandle() for further details.

A face pairing containing a wedged double-ended chain cannot model a closed minimal irreducible P^2-irreducible 3-manifold triangulation on more than two tetrahedra. See "Enumeration of non-orientable 3-manifolds using face-pairing graphs and union-find", Benjamin A. Burton, Discrete Comput. Geom. 38 (2007), no. 3, 527–571.

Returns: true if and only if this face pairing contains a wedged double-ended chain.

◆ isCanonical()

bool regina::detail::FacetPairingBase< dim >::isCanonical ( ) const

inherited

Determines whether this facet pairing is in canonical form, i.e., is a lexicographically minimal representative of its isomorphism class.

Isomorphisms of facet pairings correspond to relabellings of simplices and relabellings of the (dim + 1) facets within each simplex.

Facet pairings are ordered by lexicographical comparison of dest(0,0), dest(0,1), ..., dest(size()-1,dim).

Precondition: This facet pairing is connected, i.e., it is possible to reach any simplex from any other simplex via a series of matched facet pairs.

Returns: true if and only if this facet pairing is in canonical form.

◆ isCanonicalInternal()

bool regina::detail::FacetPairingBase< dim >::isCanonicalInternal ( IsoList & list ) const

protectedinherited

Determines whether this facet pairing is in canonical (smallest lexicographical) form, given a small set of assumptions.

If this facet pairing is in canonical form, the given list will be filled with the set of all combinatorial automorphisms of this facet pairing. If not, the given list will be left empty.

Precondition: The given list is empty.; For each simplex t, the only case in which dest(t,i) is greater than dest(t,i+1) is where facets (t,i) and (t,i+1) are paired together.; For each simplex t > 0, it is true that dest(t,0).simp < t.; The sequence dest(1,0), dest(2,0), ..., dest(n-1,0) is strictly increasing, where n is the total number of simplices under investigation.

Parameters

list	the list into which automorphisms will be placed if appropriate.

Returns: true if and only if this facet pairing is in canonical form.

◆ isClosed()

bool regina::detail::FacetPairingBase< dim >::isClosed ( ) const

inherited

Determines whether this facet pairing is closed.

A closed facet pairing has no unmatched facets.

◆ isUnmatched() [1/2]

bool regina::detail::FacetPairingBase< dim >::isUnmatched ( const FacetSpec< dim > & source ) const

inlineinherited

Determines whether the given simplex facet has been left deliberately unmatched.

Precondition: The given facet is a real simplex facet (not boundary, before-the-start or past-the-end).

Parameters

source the facet under investigation.

Returns: true if the given facet has been left unmatched, or false if the given facet is paired with some other facet.

◆ isUnmatched() [2/2]

bool regina::detail::FacetPairingBase< dim >::isUnmatched	(	size_t	simp,
		unsigned	facet
	)		const

inlineinherited

Determines whether the given simplex facet has been left deliberately unmatched.

Parameters

simp	the simplex under investigation (this must be strictly less than the total number of simplices under consideration).
facet	the facet of the given simplex under investigation (between 0 and dim inclusive).

Returns: true if the given facet has been left unmatched, or false if the given facet is paired with some other facet.

◆ noDest() [1/2]

bool regina::detail::FacetPairingBase< dim >::noDest ( const FacetSpec< dim > & source ) const

inlineprotectedinherited

Determines whether the matching for the given simplex facet has not yet been determined.

This is signalled by a facet matched to itself.

Precondition: The given facet is a real simplex facet (not boundary, before-the-start or past-the-end).

Parameters

source the facet under investigation.

Returns: true if the matching for the given facet has not yet been determined, or false otherwise.

◆ noDest() [2/2]

bool regina::detail::FacetPairingBase< dim >::noDest	(	size_t	simp,
		unsigned	facet
	)		const

inlineprotectedinherited

Determines whether the matching for the given simplex facet has not yet been determined.

This is signalled by a facet matched to itself.

Parameters

simp	the simplex under investigation (this must be strictly less than the total number of simplices under consideration).
facet	the facet of the given simplex under investigation (between 0 and dim inclusive).

Returns: true if the matching for the given facet has not yet been determined, or false otherwise.

◆ operator!=()

bool regina::detail::FacetPairingBase< dim >::operator!= ( const FacetPairing< dim > & other ) const

inherited

Determines if this and the given facet pairing are not identical.

Parameters

other the facet pairing to compare with this.

Returns: true if and only if this and the given facet pairing are not identical.

◆ operator=() [1/2]

FacetPairing & regina::FacetPairing< 3 >::operator= ( const FacetPairing< 3 > & src )

default

Copies the given face pairing into this face pairing.

It does not matter if this and the given face pairing use different numbers of tetrahedra; if they do then this face pairing will be resized accordingly.

This operator induces a deep copy of src.

Parameters

src	the facet pairing to copy.

Returns: a reference to this face pairing.

◆ operator=() [2/2]

FacetPairing & regina::FacetPairing< 3 >::operator= ( FacetPairing< 3 > && src )

defaultnoexcept

Moves the given face pairing into this facet pairing.

This is a fast (constant time) operation.

It does not matter if this and the given face pairing use different numbers of tetrahedra; if they do then this face pairing will be resized accordingly.

The face pairing that is passed (src) will no longer be usable.

Parameters

src	the face pairing to move.

Returns: a reference to this face pairing.

◆ operator==()

bool regina::detail::FacetPairingBase< dim >::operator== ( const FacetPairing< dim > & other ) const

inherited

Determines if this and the given facet pairing are identical.

Parameters

other the facet pairing to compare with this.

Returns: true if and only if this and the given facet pairing are identical.

◆ operator[]() [1/2]

FacetSpec< dim > & regina::detail::FacetPairingBase< dim >::operator[] ( const FacetSpec< dim > & source )

inlineprotectedinherited

Returns the other facet to which the given simplex facet is paired.

This is a convenience operator whose behaviour is identical to that of dest(const FacetSpec<dim>&).

If the given facet is left deliberately unmatched, the value returned will be boundary (as returned by FacetSpec<dim>::isBoundary()).

Precondition: The given facet is a real simplex facet (not boundary, before-the-start or past-the-end).

Parameters

source the facet under investigation.

Returns: the other facet to which the given facet is paired.

◆ operator[]() [2/2]

const FacetSpec< dim > & regina::detail::FacetPairingBase< dim >::operator[] ( const FacetSpec< dim > & source ) const

inlineinherited

Returns the other facet to which the given simplex facet is paired.

This is a convenience operator whose behaviour is identical to that of dest(const FacetSpec<dim>&).

If the given facet is left deliberately unmatched, the value returned will be boundary (as returned by FacetSpec<dim>::isBoundary()).

Precondition: The given facet is a real simplex facet (not boundary, before-the-start or past-the-end).

Python: This routine returns by value, not by reference, since Python cannot enforce constness otherwise.

Parameters

source the facet under investigation.

Returns: the other facet to which the given facet is paired.

◆ size()

size_t regina::detail::FacetPairingBase< dim >::size

inlineinherited

Returns the number of simplices whose facets are described by this facet pairing.

Returns: the number of simplices under consideration.

◆ str()

template<class T , bool supportsUtf8 = false>

std::string regina::Output< T, supportsUtf8 >::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::detail::FacetPairingBase< dim >::swap ( FacetPairingBase< 3 > & other )

inlinenoexceptinherited

Swaps the contents of this and the given facet pairing.

Parameters

other the facet pairing whose contents are to be swapped with this.

◆ toTextRep()

std::string regina::detail::FacetPairingBase< dim >::toTextRep ( ) const

inherited

Returns a text-based representation of this facet pairing that can be used to reconstruct the facet pairing.

This reconstruction is done through routine fromTextRep().

The text produced is not particularly readable; for a human-readable text representation, see routine str() instead.

The string returned will contain no newlines.

Returns: a text-based representation of this facet pairing.

◆ utf8()

template<class T , bool supportsUtf8 = false>

std::string regina::Output< T, supportsUtf8 >::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.

◆ writeDot()

void regina::detail::FacetPairingBase< dim >::writeDot	(	std::ostream &	out,
		const char *	prefix = `nullptr`,
		bool	subgraph = `false`,
		bool	labels = `false`
	)		const

inherited

Writes the graph corresponding to this facet pairing in the Graphviz DOT language.

Every vertex of this graph represents a simplex, and every edge represents a pair of simplex facets that are joined together. Note that for a closed triangulation this graph will be entirely (dim + 1)-valent; for triangulations with boundary facets, some graph vertices will have degree dim or less.

The graph can either be written as a complete DOT graph, or as a clustered subgraph within some larger DOT graph (according to whether the argument subgraph is passed as false or true).

If a complete DOT graph is being written, the output may be used as a standalone DOT file ready for use with Graphviz.

If a subgraph is being written, the output will contain a single subgraph section that should be inserted into some larger DOT file. Note that the output generated by writeDotHeader(), followed by one or more subgraphs and then a closing curly brace will suffice. The subgraph name will begin with the string pairing_.

The argument prefix will be prepended to the name of each graph vertex, and will also be used in the name of the graph or subgraph. Using unique prefixes becomes important if you are calling writeDot() several times to generate several subgraphs for use in a single DOT file. If the prefix argument is null or empty then a default prefix will be used.

Note that this routine generates undirected graphs, not directed graphs. The final DOT file should be used with either the neato or fdp programs shipped with Graphviz.

Python: Not present; instead use the variant dot() that returns a string.

Parameters

out	the output stream to which to write.
prefix	a string to prepend to the name of each graph vertex, and to include in the graph or subgraph name; see above for details.
subgraph	`false` if a complete standalone DOT graph should be output, or `true` if a clustered subgraph should be output for use in some larger DOT file.
labels	indicates whether graph vertices will be labelled with the corresponding simplex numbers. This feature is currently experimental, and the default is `false`.

See also: http://www.graphviz.org/

◆ writeDotHeader()

static void regina::detail::FacetPairingBase< dim >::writeDotHeader	(	std::ostream &	out,
		const char *	graphName = `nullptr`
	)

staticinherited

Writes header information for a Graphviz DOT file that will describe the graphs for one or more facet pairings.

See the writeDot() documentation for further information on such graphs.

The output will be in the Graphviz DOT language, and will include appropriate display settings for graphs, edges and nodes. The opening brace for a graph section of the DOT file is included.

This routine may be used with writeDot() to generate a single DOT file containing the graphs for several different facet pairings. A complete DOT file can be produced by calling this routine, then calling writeDot() in subgraph mode for each facet pairing, then outputting a final closing curly brace.

Note that if you require a DOT file containing the graph for only a single facet pairing, this routine is unnecessary; you may simply call writeDot() in full graph mode instead.

This routine is suitable for generating undirected graphs, not directed graphs. The final DOT file should be used with either the neato or fdp programs shipped with Graphviz.

Python: Not present; instead use the variant dotHeader() that returns a string.

Parameters

out	the output stream to which to write.
graphName	the name of the graph in the DOT file. If this is null or empty then a default graph name will be used.

See also: http://www.graphviz.org/

◆ writeTextLong()

void regina::ShortOutput< FacetPairingBase< dim > , false >::writeTextLong ( std::ostream & out ) const

inlineinherited

A default implementation for detailed output.

This routine simply calls T::writeTextShort() and appends a final newline.

Python: Not present; instead you can call detail() from the subclass T, which returns this output as a string.

Parameters

out	the output stream to which to write.

◆ writeTextShort()

void regina::detail::FacetPairingBase< dim >::writeTextShort ( std::ostream & out ) const

inherited

Writes a human-readable representation of this facet pairing to the given output stream.

The string returned will contain no newlines.

Python: Not present; use str() instead.

Parameters

out	the output stream to which to write.

Member Data Documentation

◆ pairs_

FacetSpec<dim>* regina::detail::FacetPairingBase< dim >::pairs_

protectedinherited

The other facet to which each simplex facet is paired.

If a simplex facet is left unmatched, the corresponding element of this array will be boundary (as returned by FacetSpec<dim>::isBoundary()). If the destination for a particular facet has not yet been decided, the facet will be paired to itself.

◆ size_

size_t regina::detail::FacetPairingBase< dim >::size_

protectedinherited

The number of simplices under consideration.

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

triangulation/facetpairing3.h

Public Types

Public Member Functions

Protected Attributes

Friends

Input and Output

Detailed Description

Member Typedef Documentation

◆ IsoList

Constructor & Destructor Documentation

◆ FacetPairing() [1/4]

◆ FacetPairing() [2/4]

◆ FacetPairing() [3/4]

◆ FacetPairing() [4/4]

Member Function Documentation

◆ dest() [1/4]

◆ dest() [2/4]

◆ dest() [3/4]

◆ dest() [4/4]

◆ detail()

◆ dot()

◆ dotHeader()

◆ findAllPairings()

◆ findAutomorphisms()

◆ followChain()

◆ fromTextRep()

◆ hasBrokenDoubleEndedChain()

◆ hasDoubleSquare()

◆ hasDoubleStar()

◆ hasOneEndedChainWithDoubleHandle()

◆ hasOneEndedChainWithStrayBigon()

◆ hasSingleStar()

◆ hasTripleEdge()

◆ hasTripleOneEndedChain()

◆ hasWedgedDoubleEndedChain()

◆ isCanonical()

◆ isCanonicalInternal()

◆ isClosed()

◆ isUnmatched() [1/2]

◆ isUnmatched() [2/2]

◆ noDest() [1/2]

◆ noDest() [2/2]

◆ operator!=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ size()

◆ str()

◆ swap()

◆ toTextRep()

◆ utf8()

◆ writeDot()

◆ writeDotHeader()

◆ writeTextLong()

◆ writeTextShort()

Member Data Documentation

◆ pairs_

◆ size_