Public Member Functions | Static Public Member Functions | Protected Attributes

regina::NIsomorphism Class Reference
[Triangulations]

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

#include <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.
NPermfacePerm (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.
NPerm 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.
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.

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.
NPermmFacePerm
 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:
Tested in the test suite, though not exhaustively.
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.

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

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

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-2009, Ben Burton
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).