Regina Calculation Engine
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
regina::NFacePairing Class Reference

Represents a specific pairwise matching of tetrahedron faces. More...

#include <census/nfacepairing.h>

Inheritance diagram for regina::NFacePairing:
regina::NGenericFacetPairing< 3 > regina::NThread

Public Types

typedef DimTraits< dim >
::FacetPairing 
FacetPairing
 The facet pairing class specific to this dimension. More...
 
typedef DimTraits< dim >
::Isomorphism 
Isomorphism
 The isomorphism class used for triangulations in this dimension. More...
 
typedef DimTraits< dim >::Perm Perm
 The permutation class used to glue together facets of simplices when building triangulations in this dimension. More...
 
typedef DimTraits< dim >::Simplex Simplex
 The class that represents a top-level simplex of a triangulation in this dimension. More...
 
typedef DimTraits< dim >
::Triangulation 
Triangulation
 The triangulation class specific to this dimension. More...
 
typedef std::list< Isomorphism * > IsoList
 A list of isomorphisms on pairwise matchings of simplex facets. More...
 
typedef void(* Use )(const FacetPairing *, const IsoList *, void *)
 A routine that can do arbitrary processing upon a facet pairing and its automorphisms. More...
 

Public Member Functions

 NFacePairing (const NFacePairing &cloneMe)
 Creates a new face pairing that is a clone of the given face pairing. More...
 
 NFacePairing (const NTriangulation &tri)
 Creates the face pairing of the given 3-manifold triangulation. More...
 
unsigned getNumberOfTetrahedra () const
 A legacy alias for size(), provided for backward compatibility only. More...
 
void followChain (unsigned &tet, NFacePair &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...
 
bool start (void *args=0, bool deleteAfterwards=false)
 Starts a new thread and performs run() within this new thread. More...
 
void join ()
 Waits for a previously-started thread to terminate. More...
 
Basic Queries
unsigned size () const
 Returns the number of simplices whose facets are described by this facet pairing. More...
 
const NFacetSpec< dim > & dest (const NFacetSpec< dim > &source) const
 Returns the other facet to which the given simplex facet is paired. More...
 
const NFacetSpec< dim > & dest (unsigned simp, unsigned facet) const
 Returns the other facet to which the given simplex facet is paired. More...
 
const NFacetSpec< dim > & operator[] (const NFacetSpec< dim > &source) const
 Returns the other facet to which the given simplex facet is paired. More...
 
bool isUnmatched (const NFacetSpec< dim > &source) const
 Determines whether the given simplex facet has been left deliberately unmatched. More...
 
bool isUnmatched (unsigned 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...
 
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...
 
void findAutomorphisms (IsoList &list) const
 Fills the given list with the set of all combinatorial automorphisms of this facet pairing. More...
 
Input and Output
std::string toString () const
 A deprecated alias for str(), which returns a human-readable representation of this facet pairing. More...
 
std::string str () const
 Returns a human-readable representation of this facet pairing. 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=0, 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=0, bool subgraph=false, bool labels=false) const
 Returns a Graphviz DOT representation of the graph that describes this facet pairing. More...
 
Internal Routines
void * run (void *param)
 Internal to findAllPairings(). More...
 

Static Public Member Functions

static FacetPairingfromTextRep (const std::string &rep)
 Reconstructs a facet pairing from a text-based representation. More...
 
static void writeDotHeader (std::ostream &out, const char *graphName=0)
 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=0)
 Returns header information for a Graphviz DOT file that will describe the graphs for one or more facet pairings. More...
 
static bool findAllPairings (unsigned nSimplices, NBoolSet boundary, int nBdryFacets, Use use, void *useArgs=0, bool newThread=false)
 Generates all possible facet pairings satisfying the given constraints. More...
 
static bool start (void *(*routine)(void *), void *args, NThreadID *id)
 Starts a new thread that performs the given routine. More...
 
static void yield ()
 Causes the currently running thread to voluntarily relinquish the processor. More...
 

Protected Member Functions

NFacetSpec< dim > & dest (const NFacetSpec< dim > &source)
 Returns the other facet to which the given simplex facet is paired. More...
 
NFacetSpec< dim > & dest (unsigned simp, unsigned facet)
 Returns the other facet to which the given simplex facet is paired. More...
 
NFacetSpec< dim > & operator[] (const NFacetSpec< dim > &source)
 Returns the other facet to which the given simplex facet is paired. More...
 
bool noDest (const NFacetSpec< dim > &source) const
 Determines whether the matching for the given simplex facet has not yet been determined. More...
 
bool noDest (unsigned 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...
 

Protected Attributes

unsigned size_
 The number of simplices under consideration. More...
 
NFacetSpec< dim > * pairs_
 The other facet to which each simplex facet is paired. More...
 

Friends

class NGenericFacetPairing< 3 >
 

Detailed Description

Represents a specific pairwise matching of tetrahedron faces.

Given a fixed number of tetrahedra, each tetrahedron face is either paired with some other tetrahedron face (which is in turn paired with it) or remains unmatched. A tetrahedron face cannot be paired with itself.

Such a matching models part of the structure of a triangulation, in which each tetrahedron face is either glued to some other tetrahedron face (which is in turn glued to it) or is an unglued boundary face.

Note that if this pairing is used to construct an actual triangulation, the individual gluing permutations will still need to be specified; they are not a part of this structure.

Member Typedef Documentation

The facet pairing class specific to this dimension.

This is typically a subclass of NGenericFacetPairing<dim>.

typedef std::list<Isomorphism*> regina::NGenericFacetPairing< dim >::IsoList
inherited

A list of isomorphisms on pairwise matchings of simplex facets.

Specifically, such an isomorphism can be used to convert one pairwise matching of simplex facets (as described by class NGenericFacetPairing) into another.

The isomorphism class used for triangulations in this dimension.

typedef DimTraits<dim>::Perm regina::NGenericFacetPairing< dim >::Perm
inherited

The permutation class used to glue together facets of simplices when building triangulations in this dimension.

typedef DimTraits<dim>::Simplex regina::NGenericFacetPairing< dim >::Simplex
inherited

The class that represents a top-level simplex of a triangulation in this dimension.

The triangulation class specific to this dimension.

typedef void(* regina::NGenericFacetPairing< dim >::Use)(const FacetPairing *, const IsoList *, void *)
inherited

A routine that can do arbitrary processing upon a facet pairing and its automorphisms.

Such routines are used to process pairings that are found when running findAllPairings().

The first parameter passed should be a facet pairing (this should not be deallocated by this routine). The second parameter should be a list of all automorphisms of this pairing (this should not be deallocated either). The third parameter may contain arbitrary data as passed to findAllPairings().

It may be assumed that the pairing is of the appropriate dimension-specific subclass (such as NFacePairing for dimension three, or Dim2EdgePairing for dimension two).

Note that the first two parameters passed might be null to signal that facet pairing generation has finished.

Constructor & Destructor Documentation

regina::NFacePairing::NFacePairing ( const NFacePairing cloneMe)
inline

Creates a new face pairing that is a clone of the given face pairing.

Parameters
cloneMethe face pairing to clone.
regina::NFacePairing::NFacePairing ( const NTriangulation tri)
inline

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

This is the face pairing that describes how the tetrahedron faces of the given triangulation are joined together, as described in the class notes.

Precondition
The given triangulation is not empty.
Parameters
trithe triangulation whose face pairing should be constructed.

Member Function Documentation

const NFacetSpec<dim>& regina::NGenericFacetPairing< dim >::dest ( const NFacetSpec< dim > &  source) const
inherited

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 NFacetSpec<dim>::isBoundary()).

Precondition
The given facet is a real simplex facet (not boundary, before-the-start or past-the-end).
Parameters
sourcethe facet under investigation.
Returns
the other facet to which the given facet is paired.
const NFacetSpec<dim>& regina::NGenericFacetPairing< dim >::dest ( unsigned  simp,
unsigned  facet 
) const
inherited

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 NFacetSpec<dim>::isBoundary()).

Parameters
simpthe simplex under investigation (this must be strictly less than the total number of simplices under consideration).
facetthe facet of the given simplex under investigation (between 0 and dim inclusive).
Returns
the other facet to which the given facet is paired.
NFacetSpec<dim>& regina::NGenericFacetPairing< dim >::dest ( const NFacetSpec< dim > &  source)
protectedinherited

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 NFacetSpec<dim>::isBoundary()).

Precondition
The given facet is a real simplex facet (not boundary, before-the-start or past-the-end).
Parameters
sourcethe facet under investigation.
Returns
the other facet to which the given facet is paired.
NFacetSpec<dim>& regina::NGenericFacetPairing< dim >::dest ( unsigned  simp,
unsigned  facet 
)
protectedinherited

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 NFacetSpec<dim>::isBoundary()).

Parameters
simpthe simplex under investigation (this must be strictly less than the total number of simplices under consideration).
facetthe facet of the given simplex under investigation (between 0 and dim inclusive).
Returns
the other facet to which the given facet is paired.
std::string regina::NGenericFacetPairing< dim >::dot ( const char *  prefix = 0,
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.
static std::string regina::NGenericFacetPairing< dim >::dotHeader ( const char *  graphName = 0)
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.
static bool regina::NGenericFacetPairing< dim >::findAllPairings ( unsigned  nSimplices,
NBoolSet  boundary,
int  nBdryFacets,
Use  use,
void *  useArgs = 0,
bool  newThread = false 
)
staticinherited

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, routine use (as passed to this function) will be called with that pairing and its automorphisms as arguments. Each pairing will be of the appropriate dimension-specific subclass (for instance, NFacePairing for dimension three, or Dim2EdgePairing for dimension two).

Once the generation of facet pairings has finished, routine use will be called once more, this time with null as its first two arguments (for the facet pairing and its automorphisms).

The facet pairing generation may be run in the current thread or as a separate thread.

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:
Not present, even in the dimension-specific subclasses.
Parameters
nSimplicesthe number of simplices whose facets should be (potentially) matched.
boundarydetermines 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.
nBdryFacetsspecifies 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.
usethe function to call upon each facet pairing that is found. The first parameter passed to this function will be a facet pairing. The second parameter will be a list of all its automorphisms (relabellings of simplices and individual simplex facets that produce the exact same pairing). The third parameter will be parameter useArgs as was passed to this routine.
useArgsthe pointer to pass as the final parameter for the function use which will be called upon each pairing found.
newThreadtrue if facet pairing generation should be performed in a separate thread, or false if generation should take place in the current thread. If this parameter is true, this routine will exit immediately (after spawning the new thread).
Returns
true if the new thread was successfully started (or if facet pairing generation has taken place in the current thread), or false if the new thread could not be started.
void regina::NGenericFacetPairing< dim >::findAutomorphisms ( IsoList list) const
inherited

Fills the given list with 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.

The automorphisms placed in the given list will be newly created; it is the responsibility of the caller of this routine to deallocate them.

Precondition
The given list is empty.
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().
Python:
Not present, even in the dimension-specific subclasses.
Parameters
listthe list into which the newly created automorphisms will be placed.
void regina::NFacePairing::followChain ( unsigned &  tet,
NFacePair 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
tetthe 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.
facesthe 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.
static FacetPairing* regina::NGenericFacetPairing< 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().

The facet pairing returned will be newly constructed; it is the responsibility of the caller of this routine to deallocate it.

Precondition
The facet pairing to be reconstructed involves at least one simplex.
Parameters
repa text-based representation of a facet pairing, as produced by routine toTextRep().
Returns
the corresponding newly constructed facet pairing, or null if the given text-based representation was invalid.
unsigned regina::NFacePairing::getNumberOfTetrahedra ( ) const
inline

A legacy alias for size(), provided for backward compatibility only.

This routine returns the number of tetrahedra whose faces are described by this face pairing.

Deprecated:
As of Regina 4.94, this routine has been renamed to size(). The old name getNumberOfTetrahedra() is provided for backward compatibility, but will be removed in some future version of Regina.
Returns
the number of tetrahedra under consideration.
bool regina::NFacePairing::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.
bool regina::NFacePairing::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.
bool regina::NFacePairing::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.
bool regina::NFacePairing::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.
bool regina::NFacePairing::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.
bool regina::NFacePairing::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.
bool regina::NFacePairing::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.
bool regina::NFacePairing::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.
bool regina::NFacePairing::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.
bool regina::NGenericFacetPairing< 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.
bool regina::NGenericFacetPairing< 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
listthe list into which automorphisms will be placed if appropriate.
Returns
true if and only if this facet pairing is in canonical form.
bool regina::NGenericFacetPairing< dim >::isClosed ( ) const
inherited

Determines whether this facet pairing is closed.

A closed facet pairing has no unmatched facets.

bool regina::NGenericFacetPairing< dim >::isUnmatched ( const NFacetSpec< dim > &  source) const
inherited

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
sourcethe 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.
bool regina::NGenericFacetPairing< dim >::isUnmatched ( unsigned  simp,
unsigned  facet 
) const
inherited

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

Parameters
simpthe simplex under investigation (this must be strictly less than the total number of simplices under consideration).
facetthe 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.
void regina::NThread::join ( )
inlineinherited

Waits for a previously-started thread to terminate.

Once this function returns, it is guaranteed that the thread is no longer running.

Precondition
This thread was started by calling the non-static start(), and with deleteAfterwards set to false (the default).
You have not already called join() on the same thread. However, you may repeatedly call start() and then join() on the same thread object (i.e., the same instance of your NThread subclass), as long as each call to start() occurs after the previous thread has finished execution.
You are not calling join() from within the thread that you are waiting to terminate. That is, you are not calling join() from within run().
bool regina::NGenericFacetPairing< dim >::noDest ( const NFacetSpec< dim > &  source) const
protectedinherited

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
sourcethe facet under investigation.
Returns
true if the matching for the given facet has not yet been determined, or false otherwise.
bool regina::NGenericFacetPairing< dim >::noDest ( unsigned  simp,
unsigned  facet 
) const
protectedinherited

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

This is signalled by a facet matched to itself.

Parameters
simpthe simplex under investigation (this must be strictly less than the total number of simplices under consideration).
facetthe 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.
const NFacetSpec<dim>& regina::NGenericFacetPairing< dim >::operator[] ( const NFacetSpec< dim > &  source) const
inherited

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 NFacetSpec<dim>&).

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

Precondition
The given facet is a real simplex facet (not boundary, before-the-start or past-the-end).
Parameters
sourcethe facet under investigation.
Returns
the other facet to which the given facet is paired.
NFacetSpec<dim>& regina::NGenericFacetPairing< dim >::operator[] ( const NFacetSpec< dim > &  source)
protectedinherited

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 NFacetSpec<dim>&).

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

Precondition
The given facet is a real simplex facet (not boundary, before-the-start or past-the-end).
Parameters
sourcethe facet under investigation.
Returns
the other facet to which the given facet is paired.
void* regina::NGenericFacetPairing< dim >::run ( void *  param)
virtualinherited

Internal to findAllPairings().

This routine should never be called directly.

Performs the actual generation of facet pairings, possibly as a separate thread. At most one copy of this routine should be running at any given time for a particular NGenericFacetPairing instance.

Python:
Not present, even in the dimension-specific subclasses.
Precondition
This object is known to be of the dimension-specific subclass FacetPairing, not an instance of the parent class NGenericFacetPairing<dim>.
Parameters
parama structure containing the parameters that were passed to findAllPairings().
Returns
the value 0.

Implements regina::NThread.

unsigned regina::NGenericFacetPairing< dim >::size ( ) const
inherited

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

Returns
the number of simplices under consideration.
bool regina::NThread::start ( void *  args = 0,
bool  deleteAfterwards = false 
)
inherited

Starts a new thread and performs run() within this new thread.

The return value of run() is ignored.

Precondition
This thread object is not already running.
Warning
If you pass deleteAfterwards as true, you must not attempt to access this thread object again (since it could be deleted at any time). In particular, you will not be able to call join() to wait for the new thread to terminate.
Parameters
argsthe arguments to pass to run() when it is started.
deleteAfterwardstrue if this NThread object should be deleted once run() has finished.
Returns
true if and only if the new thread was successfully started.
static bool regina::NThread::start ( void *(*)(void *)  routine,
void *  args,
NThreadID id 
)
staticinherited

Starts a new thread that performs the given routine.

The return value of the given routine is currently ignored.

Deprecated:
This variant of start() is deprecated. You should instead create a new thread object and call the non-static start() on that objet.
Parameters
routinethe routine to run in the new thread.
argsthe arguments to pass to routine when it is started.
ida location in which the ID of the new thread will be placed, or 0 if the new thread ID is not required. If non-zero, this parameter must point to an already extisting NThreadID that may contain any value.
Returns
true if and only if the new thread was successfully started.
std::string regina::NGenericFacetPairing< dim >::str ( ) const
inherited

Returns a human-readable representation of this facet pairing.

The string returned will contain no newlines.

Python:
This implements the __str__() function.
Returns
a string representation of this pairing.
std::string regina::NGenericFacetPairing< dim >::toString ( ) const
inherited

A deprecated alias for str(), which returns a human-readable representation of this facet pairing.

Deprecated:
This routine has (at long last) been deprecated; use the simpler-to-type str() instead.
Returns
a string representation of this pairing.
std::string regina::NGenericFacetPairing< 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.
void regina::NGenericFacetPairing< dim >::writeDot ( std::ostream &  out,
const char *  prefix = 0,
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:
The out argument is not present; instead standard output is assumed.
Parameters
outthe output stream to which to write.
prefixa string to prepend to the name of each graph vertex, and to include in the graph or subgraph name; see above for details.
subgraphfalse 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.
labelsindicates 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/
static void regina::NGenericFacetPairing< dim >::writeDotHeader ( std::ostream &  out,
const char *  graphName = 0 
)
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:
The out argument is not present; instead standard output is assumed.
Parameters
outthe output stream to which to write.
graphNamethe 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/
void regina::NThread::yield ( )
inlinestaticinherited

Causes the currently running thread to voluntarily relinquish the processor.

Another thread of equal or higher priority will be given a turn instead.

Deprecated:
Use of this routine within Regina is not advised, and this routine will be removed in some future release.

Member Data Documentation

NFacetSpec<dim>* regina::NGenericFacetPairing< 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 NFacetSpec<dim>::isBoundary()). If the destination for a particular facet has not yet been decided, the facet will be paired to itself.

unsigned regina::NGenericFacetPairing< dim >::size_
protectedinherited

The number of simplices under consideration.


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

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).