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 regina::NIsomorphismIndexed

List of all members.

Public Member Functions

virtual ~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.
virtual NPerm facePerm (unsigned sourceTet) const =0
 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 Member Functions

 NIsomorphism (unsigned newSourceTetrahedra)
 Creates a new isomorphism with no initialisation.

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.


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.

This class cannot be directly instantiated; the individual subclasses correspond to different methods of storing the face permutations associated with each tetrahedron.

Test:
Tested in the test suite, though not exhaustively.
Todo:
Feature: Composition of isomorphisms.

Constructor & Destructor Documentation

regina::NIsomorphism::~NIsomorphism (  )  [inline, virtual]

Destroys this isomorphism.

regina::NIsomorphism::NIsomorphism ( unsigned  newSourceTetrahedra  )  [inline, protected]

Creates a new isomorphism with no initialisation.

Parameters:
newSourceTetrahedra the number of tetrahedra in the source triangulation; this may be zero.


Member Function Documentation

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.

int & regina::NIsomorphism::tetImage ( unsigned  sourceTet  )  [inline]

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

Parameters:
sourceTet the 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:
sourceTet the 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.

virtual NPerm regina::NIsomorphism::facePerm ( unsigned  sourceTet  )  const [pure virtual]

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:
sourceTet the 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.

Implemented in regina::NIsomorphismDirect, and regina::NIsomorphismIndexed.

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:
source the 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.

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.

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:
original the 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::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:
out the output stream to which to write.

Implements regina::ShareableObject.

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:
out the output stream to which to write.

Reimplemented from regina::ShareableObject.

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:
nTetrahedra the number of tetrahedra that the new isomorphism should operate upon.
Returns:
the newly constructed random isomorphism.


Member Data Documentation

unsigned regina::NIsomorphism::nTetrahedra [protected]

The number of tetrahedra in the source triangulation.

int* regina::NIsomorphism::mTetImage [protected]

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


The documentation for this class was generated from the following file:
Copyright © 1999-2006, 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).