Regina Calculation Engine
Public Member Functions | Static Public Member Functions | Protected Attributes
regina::NIsomorphism Class Reference

Represents a combinatorial isomorphism from one triangulation into another. More...

#include <triangulation/nisomorphism.h>

Inheritance diagram for regina::NIsomorphism:
regina::ShareableObject regina::boost::noncopyable regina::NIsomorphismDirect

List of all members.

Public Member Functions

 NIsomorphism (unsigned sourceTetrahedra)
 Creates a new isomorphism with no initialisation.
 NIsomorphism (const NIsomorphism &cloneMe)
 Creates a new isomorphism identical to the given isomorphism.
 ~NIsomorphism ()
 Destroys this isomorphism.
unsigned getSourceTetrahedra () const
 Returns the number of tetrahedra in the source triangulation associated with this isomorphism.
int & tetImage (unsigned sourceTet)
 Determines the image of the given source tetrahedron under this isomorphism.
int tetImage (unsigned sourceTet) const
 Determines the image of the given source tetrahedron under this isomorphism.
NPerm4facePerm (unsigned sourceTet)
 Returns a read-write reference to the permutation that is applied to the four faces of the given source tetrahedron under this isomorphism.
NPerm4 facePerm (unsigned sourceTet) const
 Determines the permutation that is applied to the four faces of the given source tetrahedron under this isomorphism.
NTetFace operator[] (const NTetFace &source) const
 Determines the image of the given source tetrahedron face under this isomorphism.
bool isIdentity () const
 Determines whether or not this is an identity isomorphism.
NTriangulationapply (const NTriangulation *original) const
 Applies this isomorphism to the given triangulation and returns the result as a new triangulation.
void applyInPlace (NTriangulation *tri) const
 Applies this isomorphism to the given triangulation, modifying the given triangulation directly.
void writeTextShort (std::ostream &out) const
 Writes this object in short text format to the given output stream.
void writeTextLong (std::ostream &out) const
 Writes this object in long text format to the given output stream.
- Public Member Functions inherited from regina::ShareableObject
 ShareableObject ()
 Default constructor that does nothing.
virtual ~ShareableObject ()
 Default destructor that does nothing.
std::string toString () const
 Returns the output from writeTextShort() as a string.
std::string toStringLong () const
 Returns the output from writeTextLong() as a string.

Static Public Member Functions

static NIsomorphismrandom (unsigned nTetrahedra)
 Returns a random isomorphism for the given number of tetrahedra.

Protected Attributes

unsigned nTetrahedra
 The number of tetrahedra in the source triangulation.
int * mTetImage
 The tetrahedron of the destination triangulation that each tetrahedron of the source triangulation maps to.
NPerm4mFacePerm
 The permutation applied to the four faces of each source tetrahedron.

Detailed Description

Represents a combinatorial isomorphism from one triangulation into another.

A combinatorial isomorphism from triangulation T to triangulation U is a one-to-one map f from the individual tetrahedron faces of T to the individual tetrahedron faces of U for which the following conditions hold:

Isomorphisms can be boundary complete or boundary incomplete. A boundary complete isomorphism satisfies the additional condition:

A boundary complete isomorphism thus indicates that a copy of triangulation T is present as an entire component (or components) of U, whereas a boundary incomplete isomorphism represents an embedding of a copy of triangulation T as a subcomplex of some possibly larger component (or components) of U.

Note that in all cases triangulation U may contain more tetrahedra than triangulation T.

Test:
Included in the test suite.
Todo:
Feature: Composition of isomorphisms.

Constructor & Destructor Documentation

regina::NIsomorphism::NIsomorphism ( unsigned  sourceTetrahedra)
inline

Creates a new isomorphism with no initialisation.

Python:
Not present.
Parameters:
sourceTetrahedrathe number of tetrahedra in the source triangulation associated with this isomorphism; this may be zero.
regina::NIsomorphism::NIsomorphism ( const NIsomorphism cloneMe)

Creates a new isomorphism identical to the given isomorphism.

Parameters:
cloneMethe isomorphism upon which to base the new isomorphism.
regina::NIsomorphism::~NIsomorphism ( )
inline

Destroys this isomorphism.


Member Function Documentation

NTriangulation* regina::NIsomorphism::apply ( const NTriangulation original) const

Applies this isomorphism to the given triangulation and returns the result as a new triangulation.

The given triangulation (call this T) is not modified in any way. A new triangulation (call this S) is returned, so that this isomorphism represents a one-to-one, onto and boundary complete isomorphism from T to S. That is, T and S are combinatorially identical triangulations, and this isomorphism describes the corresponding mapping between tetrahedra and tetrahedron faces.

The resulting triangulation S is newly created, and must be destroyed by the caller of this routine.

There are several preconditions to this routine. This routine does a small amount of sanity checking (and returns 0 if an error is detected), but it certainly does not check the entire set of preconditions. It is up to the caller of this routine to verify that all of the following preconditions are met.

Precondition:
The number of tetrahedra in the given triangulation is precisely the number returned by getSourceTetrahedra() for this isomorphism.
This is a valid isomorphism (i.e., it has been properly initialised, so that all tetrahedron images are non-negative and distinct, and all face permutations are real permutations of (0,1,2,3).
Each tetrahedron image for this isomorphism lies between 0 and getSourceTetrahedra()-1 inclusive (i.e., this isomorphism does not represent a mapping from a smaller triangulation into a larger triangulation).
Parameters:
originalthe triangulation to which this isomorphism should be applied.
Returns:
the resulting new triangulation, or 0 if a problem was encountered (i.e., an unmet precondition was noticed).
void regina::NIsomorphism::applyInPlace ( NTriangulation tri) const

Applies this isomorphism to the given triangulation, modifying the given triangulation directly.

This is similar to apply(), except that instead of creating a new triangulation, the tetrahedra and vertices of the given triangulation are modified directly.

See apply() for further details on how this operation is performed.

As with apply(), there are several preconditions to this routine. This routine does a small amount of sanity checking (and returns without changes if an error is detected), but it certainly does not check the entire set of preconditions. It is up to the caller of this routine to verify that all of the following preconditions are met.

Precondition:
The number of tetrahedra in the given triangulation is precisely the number returned by getSourceTetrahedra() for this isomorphism.
This is a valid isomorphism (i.e., it has been properly initialised, so that all tetrahedron images are non-negative and distinct, and all face permutations are real permutations of (0,1,2,3).
Each tetrahedron image for this isomorphism lies between 0 and getSourceTetrahedra()-1 inclusive (i.e., this isomorphism does not represent a mapping from a smaller triangulation into a larger triangulation).
Parameters:
trithe triangulation to which this isomorphism should be applied.
NPerm4 & regina::NIsomorphism::facePerm ( unsigned  sourceTet)
inline

Returns a read-write reference to the permutation that is applied to the four faces of the given source tetrahedron under this isomorphism.

Face i of source tetrahedron sourceTet will be mapped to face facePerm(sourceTet)[i] of tetrahedron tetImage(sourceTet).

Python:
Not present, though the read-only version of this routine is.
Parameters:
sourceTetthe index of the source tetrahedron containing the original four faces; this must be between 0 and getSourceTetrahedra()-1 inclusive.
Returns:
a read-write reference to the permutation applied to the four faces of the source tetrahedron.
NPerm4 regina::NIsomorphism::facePerm ( unsigned  sourceTet) const
inline

Determines the permutation that is applied to the four faces of the given source tetrahedron under this isomorphism.

Face i of source tetrahedron sourceTet will be mapped to face facePerm(sourceTet)[i] of tetrahedron tetImage(sourceTet).

Parameters:
sourceTetthe index of the source tetrahedron containing the original four faces; this must be between 0 and getSourceTetrahedra()-1 inclusive.
Returns:
the permutation applied to the four faces of the source tetrahedron.
unsigned regina::NIsomorphism::getSourceTetrahedra ( ) const
inline

Returns the number of tetrahedra in the source triangulation associated with this isomorphism.

Note that this is always less than or equal to the number of tetrahedra in the destination triangulation.

Returns:
the number of tetrahedra in the source triangulation.
bool regina::NIsomorphism::isIdentity ( ) const

Determines whether or not this is an identity isomorphism.

In an identity isomorphism, each tetrahedron image is itself, and within each tetrahedron the face/vertex permutation is the identity on (0,1,2,3).

Returns:
true if this is an identity isomorphism, or false otherwise.
NTetFace regina::NIsomorphism::operator[] ( const NTetFace source) const
inline

Determines the image of the given source tetrahedron face under this isomorphism.

Note that a value only is returned; this routine cannot be used to alter the isomorphism.

Parameters:
sourcethe given source tetrahedron face; this must be one of the four faces of one of the getSourceTetrahedra() tetrahedra in the source triangulation.
Returns:
the image of the source tetrahedron face under this isomorphism.
static NIsomorphism* regina::NIsomorphism::random ( unsigned  nTetrahedra)
static

Returns a random isomorphism for the given number of tetrahedra.

This isomorphism will reorder tetrahedra 0 to nTetrahedra-1 in a random fashion, and for each tetrahedron a random permutation of its four vertices will be selected.

The isomorphism returned is newly constructed, and must be destroyed by the caller of this routine.

Note that both the STL random number generator and the standard C function rand() are used in this routine. All possible isomorphisms for the given number of tetrahedra are equally likely.

Parameters:
nTetrahedrathe number of tetrahedra that the new isomorphism should operate upon.
Returns:
the newly constructed random isomorphism.
int & regina::NIsomorphism::tetImage ( unsigned  sourceTet)
inline

Determines the image of the given source tetrahedron under this isomorphism.

Python:
Not present, though the read-only version of this routine is.
Parameters:
sourceTetthe index of the source tetrahedron; this must be between 0 and getSourceTetrahedra()-1 inclusive.
Returns:
a reference to the index of the destination tetrahedron that the source tetrahedron maps to.
int regina::NIsomorphism::tetImage ( unsigned  sourceTet) const
inline

Determines the image of the given source tetrahedron under this isomorphism.

Parameters:
sourceTetthe index of the source tetrahedron; this must be between 0 and getSourceTetrahedra()-1 inclusive.
Returns:
the index of the destination tetrahedron that the source tetrahedron maps to.
void regina::NIsomorphism::writeTextLong ( std::ostream &  out) const
virtual

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

The output should provided the user with all the information they could want. The output should end with a newline.

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

Python:
The parameter out does not exist; standard output will be used.
Parameters:
outthe output stream to which to write.

Reimplemented from regina::ShareableObject.

void regina::NIsomorphism::writeTextShort ( std::ostream &  out) const
virtual

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

The output should fit on a single line and no newline should be written.

Python:
The parameter out does not exist; standard output will be used.
Parameters:
outthe output stream to which to write.

Implements regina::ShareableObject.


Member Data Documentation

NPerm4* regina::NIsomorphism::mFacePerm
protected

The permutation applied to the four faces of each source tetrahedron.

int* regina::NIsomorphism::mTetImage
protected

The tetrahedron of the destination triangulation that each tetrahedron of the source triangulation maps to.

unsigned regina::NIsomorphism::nTetrahedra
protected

The number of tetrahedra in the source triangulation.


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

Copyright © 1999-2012, The Regina development team
This software is released under the GNU General Public License.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@debian.org).