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

Represents a combinatorial isomorphism from one 2-manifold triangulation into another. More...

#include <dim2/dim2isomorphism.h>

Inheritance diagram for regina::Dim2Isomorphism:
regina::NGenericIsomorphism< 2 > regina::ShareableObject regina::boost::noncopyable

Public Types

typedef DimTraits< dim >
::Isomorphism 
Isomorphism
 The isomorphism class used by triangulations of this specific 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...
 

Public Member Functions

 Dim2Isomorphism (unsigned sourceTriangles)
 Creates a new isomorphism with no initialisation. More...
 
 Dim2Isomorphism (const Dim2Isomorphism &cloneMe)
 Creates a new isomorphism identical to the given isomorphism. More...
 
unsigned getSourceTriangles () const
 Returns the number of triangles in the source triangulation associated with this isomorphism. More...
 
int & triImage (unsigned sourceTriangle)
 Determines the image of the given source triangle under this isomorphism. More...
 
int triImage (unsigned sourceTriangle) const
 Determines the image of the given source triangle under this isomorphism. More...
 
NPerm3edgePerm (unsigned sourceTriangle)
 Returns a read-write reference to the permutation that is applied to the three edges of the given source triangle under this isomorphism. More...
 
NPerm3 edgePerm (unsigned sourceTriangle) const
 Determines the permutation that is applied to the three edges of the given source triangle under this isomorphism. More...
 
unsigned getSourceSimplices () const
 Returns the number of simplices in the source triangulation associated with this isomorphism. More...
 
int & simpImage (unsigned sourceSimp)
 Determines the image of the given source simplex under this isomorphism. More...
 
int simpImage (unsigned sourceSimp) const
 Determines the image of the given source simplex under this isomorphism. More...
 
PermfacetPerm (unsigned sourceSimp)
 Returns a read-write reference to the permutation that is applied to the (dim + 1) facets of the given source simplex under this isomorphism. More...
 
Perm facetPerm (unsigned sourceSimp) const
 Determines the permutation that is applied to the (dim + 1) facets of the given source simplex under this isomorphism. More...
 
NFacetSpec< dim > operator[] (const NFacetSpec< dim > &source) const
 Determines the image of the given source simplex facet under this isomorphism. More...
 
bool isIdentity () const
 Determines whether or not this is an identity isomorphism. More...
 
Triangulationapply (const Triangulation *original) const
 This NGenericIsomorphism object represents a combinatorial identification from a triangulation T to a triangulation U. More...
 
void applyInPlace (Triangulation *tri) const
 Applies this isomorphism to the given triangulation, modifying the given triangulation directly. More...
 
void writeTextShort (std::ostream &out) const
 Writes this object in short text format to the given output stream. More...
 
void writeTextLong (std::ostream &out) const
 Writes this object in long text format to the given output stream. More...
 
Input and Output
std::string str () const
 Returns the output from writeTextShort() as a string. More...
 
std::string toString () const
 A deprecated alias for str(), which returns the output from writeTextShort() as a string. More...
 
std::string detail () const
 Returns the output from writeTextLong() as a string. More...
 
std::string toStringLong () const
 A deprecated alias for detail(), which returns the output from writeTextLong() as a string. More...
 

Static Public Member Functions

static Isomorphismrandom (unsigned nSimplices)
 Returns a random isomorphism for the given number of simplices. More...
 

Protected Attributes

unsigned nSimplices_
 The number of simplices in the source triangulation. More...
 
int * simpImage_
 The simplex of the destination triangulation that each simplex of the source triangulation maps to. More...
 
PermfacetPerm_
 The permutation applied to the facets of each source simplex. More...
 

Detailed Description

Represents a combinatorial isomorphism from one 2-manifold triangulation into another.

In essence, a combinatorial isomorphism from triangulation T to triangulation U is a one-to-one map from the triangles of T to the triangles of U that allows relabelling of both the triangles and their edges (or equivalently, their vertices), and that preserves gluings across adjacent triangles.

More precisely: An isomorphism consists of (i) a one-to-one map f from the triangles of T to the triangles of U, and (ii) for each triangle S of T, a permutation f_S of the edges (0,1,2) of S, for which the following condition holds:

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 triangles than triangulation T.

Member Typedef Documentation

The isomorphism class used by triangulations of this specific dimension.

Typically this is a subclass of NGenericIsomorphism<dim>.

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

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

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

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

The triangulation class specific to this dimension.

Constructor & Destructor Documentation

regina::Dim2Isomorphism::Dim2Isomorphism ( unsigned  sourceTriangles)
inline

Creates a new isomorphism with no initialisation.

Python:
Not present.
Parameters
sourceTrianglesthe number of triangles in the source triangulation associated with this isomorphism; this may be zero.
regina::Dim2Isomorphism::Dim2Isomorphism ( const Dim2Isomorphism cloneMe)
inline

Creates a new isomorphism identical to the given isomorphism.

Parameters
cloneMethe isomorphism upon which to base the new isomorphism.

Member Function Documentation

Triangulation* regina::NGenericIsomorphism< dim >::apply ( const Triangulation original) const
inherited

This NGenericIsomorphism object represents a combinatorial identification from a triangulation T to a triangulation U.

This routine produces the triangulation U, i.e. the range. The input parameter (original) represents the domain, T.

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

The resulting triangulation U 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 simplices in the given triangulation is precisely the number returned by getSourceSimplices() for this isomorphism.
This is a valid isomorphism (i.e., it has been properly initialised, so that all simplex images are non-negative and distinct, and all facet permutations are real permutations of (0,...,dim).
Each simplex image for this isomorphism lies between 0 and getSourceSimplices()-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::NGenericIsomorphism< dim >::applyInPlace ( Triangulation tri) const
inherited

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 simplices 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 simplices in the given triangulation is precisely the number returned by getSourceSimplices() for this isomorphism.
This is a valid isomorphism (i.e., it has been properly initialised, so that all simplex images are non-negative and distinct, and all facet permutations are real permutations of (0,...,dim).
Each simplex image for this isomorphism lies between 0 and getSourceSimplices()-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.
std::string regina::ShareableObject::detail ( ) const
inherited

Returns the output from writeTextLong() as a string.

Returns
a long text representation of this object.
NPerm3 & regina::Dim2Isomorphism::edgePerm ( unsigned  sourceTriangle)
inline

Returns a read-write reference to the permutation that is applied to the three edges of the given source triangle under this isomorphism.

Edge i of source triangle sourceTriangle will be mapped to edge facetPerm(sourceTriangle)[i] of triangle simpImage(sourceTriangle).

This is a convenience routine specific to two dimensions, and is identical to the dimension-agnostic routine facetPerm().

Python:
Not present, though the read-only version of this routine is.
Parameters
sourceTrianglethe index of the source triangle containing the original three edges; this must be between 0 and getSourceTriangles()-1 inclusive.
Returns
a read-write reference to the permutation applied to the three edges of the source triangle.
NPerm3 regina::Dim2Isomorphism::edgePerm ( unsigned  sourceTriangle) const
inline

Determines the permutation that is applied to the three edges of the given source triangle under this isomorphism.

Edge i of source triangle sourceTriangle will be mapped to triangle facetPerm(sourceTriangle)[i] of triangle simpImage(sourceTriangle).

This is a convenience routine specific to two dimensions, and is identical to the dimension-agnostic routine facetPerm().

Parameters
sourceTrianglethe index of the source triangle containing the original three edges; this must be between 0 and getSourceTriangles()-1 inclusive.
Returns
the permutation applied to the three edges of the source triangle.
Perm& regina::NGenericIsomorphism< dim >::facetPerm ( unsigned  sourceSimp)
inherited

Returns a read-write reference to the permutation that is applied to the (dim + 1) facets of the given source simplex under this isomorphism.

Facet i of source simplex sourceSimp will be mapped to facet facetPerm(sourceSimp)[i] of simplex simpImage(sourceSimp).

Python:
This is not available for Python users, even in the dimension-specific subclasses. However, the read-only version of this routine is.
Parameters
sourceSimpthe index of the source simplex containing the original (dim + 1) facets; this must be between 0 and getSourceSimplices()-1 inclusive.
Returns
a read-write reference to the permutation applied to the facets of the source simplex.
Perm regina::NGenericIsomorphism< dim >::facetPerm ( unsigned  sourceSimp) const
inherited

Determines the permutation that is applied to the (dim + 1) facets of the given source simplex under this isomorphism.

Facet i of source simplex sourceSimp will be mapped to face facetPerm(sourceSimp)[i] of simplex simpImage(sourceSimp).

Parameters
sourceSimpthe index of the source simplex containing the original (dim + 1) facets; this must be between 0 and getSourceSimplices()-1 inclusive.
Returns
the permutation applied to the facets of the source simplex.
unsigned regina::NGenericIsomorphism< dim >::getSourceSimplices ( ) const
inherited

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

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

Returns
the number of simplices in the source triangulation.
unsigned regina::Dim2Isomorphism::getSourceTriangles ( ) const
inline

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

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

This is a convenience routine specific to two dimensions, and is identical to the dimension-agnostic routine getSourceSimplices().

Returns
the number of triangles in the source triangulation.
bool regina::NGenericIsomorphism< dim >::isIdentity ( ) const
inherited

Determines whether or not this is an identity isomorphism.

In an identity isomorphism, each simplex image is itself, and within each simplex the facet/vertex permutation is the identity permutation.

Returns
true if this is an identity isomorphism, or false otherwise.
NFacetSpec<dim> regina::NGenericIsomorphism< dim >::operator[] ( const NFacetSpec< dim > &  source) const
inherited

Determines the image of the given source simplex facet under this isomorphism.

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

Parameters
sourcethe given source simplex facet; this must be one of the (dim + 1) facets of one of the getSourceSimplices() simplices in the source triangulation.
Returns
the image of the source simplex facet under this isomorphism.
static Isomorphism* regina::NGenericIsomorphism< dim >::random ( unsigned  nSimplices)
staticinherited

Returns a random isomorphism for the given number of simplices.

This isomorphism will reorder simplices 0 to nSimplices-1 in a random fashion, and for each simplex a random permutation of its (dim + 1) vertices will be selected.

The isomorphism will be newly constructed, and must be destroyed by the caller of this routine. The new isomorphism will be of the appropriate dimension-specific subclass (e.g., NIsomorphism for dim=3, or Dim2Isomorphism for dim=2).

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 simplices are equally likely.

Parameters
nSimplicesthe number of simplices that the new isomorphism should operate upon.
Returns
the newly constructed random isomorphism.
int& regina::NGenericIsomorphism< dim >::simpImage ( unsigned  sourceSimp)
inherited

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

Python:
This is not available for Python users, even in the dimension-specific subclasses. However, the read-only version of this routine is.
Parameters
sourceSimpthe index of the source simplex; this must be between 0 and getSourceSimplices()-1 inclusive.
Returns
a reference to the index of the destination simplex that the source simplex maps to.
int regina::NGenericIsomorphism< dim >::simpImage ( unsigned  sourceSimp) const
inherited

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

Parameters
sourceSimpthe index of the source simplex; this must be between 0 and getSourceSimplices()-1 inclusive.
Returns
the index of the destination simplex that the source simplex maps to.
std::string regina::ShareableObject::str ( ) const
inherited

Returns the output from writeTextShort() as a string.

Python:
This implements the __str__() function.
Returns
a short text representation of this object.
std::string regina::ShareableObject::toString ( ) const
inlineinherited

A deprecated alias for str(), which returns the output from writeTextShort() as a string.

Deprecated:
This routine has (at long last) been deprecated; use the simpler-to-type str() instead.
Returns
a short text representation of this object.
std::string regina::ShareableObject::toStringLong ( ) const
inlineinherited

A deprecated alias for detail(), which returns the output from writeTextLong() as a string.

Deprecated:
This routine has (at long last) been deprecated; use the simpler-to-type detail() instead.
Returns
a long text representation of this object.
int & regina::Dim2Isomorphism::triImage ( unsigned  sourceTriangle)
inline

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

This is a convenience routine specific to two dimensions, and is identical to the dimension-agnostic routine simpImage().

Python:
Not present, though the read-only version of this routine is.
Parameters
sourceTrianglethe index of the source triangle; this must be between 0 and getSourceSimplices()-1 inclusive.
Returns
a reference to the index of the destination triangle that the source triangle maps to.
int regina::Dim2Isomorphism::triImage ( unsigned  sourceTriangle) const
inline

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

This is a convenience routine specific to two dimensions, and is identical to the dimension-agnostic routine simpImage().

Parameters
sourceTrianglethe index of the source triangle; this must be between 0 and getSourceSimplices()-1 inclusive.
Returns
the index of the destination triangle that the source triangle maps to.
void regina::NGenericIsomorphism< dim >::writeTextLong ( std::ostream &  out) const
virtualinherited

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

The output should provide the user with all the information they could want. The output should be human-readable, should not contain extremely long lines (so users can read the output in a terminal), and should end with a final 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::NGenericIsomorphism< dim >::writeTextShort ( std::ostream &  out) const
virtualinherited

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

The output should be human-readable, should fit on a single line, and should not end with a newline.

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

Perm* regina::NGenericIsomorphism< dim >::facetPerm_
protectedinherited

The permutation applied to the facets of each source simplex.

unsigned regina::NGenericIsomorphism< dim >::nSimplices_
protectedinherited

The number of simplices in the source triangulation.

int* regina::NGenericIsomorphism< dim >::simpImage_
protectedinherited

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


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