Regina Calculation Engine
Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
regina::Isomorphism< dim > Class Template Reference

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

#include <generic/isomorphism.h>

Inheritance diagram for regina::Isomorphism< dim >:
regina::detail::IsomorphismBase< dim > regina::Output< IsomorphismBase< dim > >

Public Member Functions

 Isomorphism (unsigned nSimplices)
 Creates a new isomorphism with no initialisation. More...
 
 Isomorphism (const Isomorphism &copy)
 Creates a copy of the given isomorphism. More...
 
unsigned size () const
 Returns the number of simplices in the source triangulation associated with this isomorphism. More...
 
REGINA_DEPRECATED unsigned getSourceSimplices () const
 A deprecated alias for size(), which 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...
 
NPerm< dim+1 > & facetPerm (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...
 
NPerm< dim+1 > facetPerm (unsigned sourceSimp) const
 Determines the permutation that is applied to the (dim + 1) facets of the given source simplex under this isomorphism. More...
 
FacetSpec< dim > operator[] (const FacetSpec< 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...
 
Triangulation< dim > * apply (const Triangulation< dim > *original) const
 Applies this isomorphism to the given triangulation, and returns the result as a new triangulation. More...
 
void applyInPlace (Triangulation< dim > *tri) const
 Applies this isomorphism to the given triangulation, modifying the given triangulation directly. More...
 
void writeTextShort (std::ostream &out) const
 Writes a short text representation of this object to the given output stream. More...
 
void writeTextLong (std::ostream &out) const
 Writes a detailed text representation of this object to the given output stream. More...
 
std::string str () const
 Returns a short text representation of this object. More...
 
std::string utf8 () const
 Returns a short text representation of this object using unicode characters. More...
 
std::string detail () const
 Returns a detailed text representation of this object. More...
 
REGINA_DEPRECATED std::string toString () const
 A deprecated alias for str(). More...
 
REGINA_DEPRECATED std::string toStringLong () const
 A deprecated alias for detail(). More...
 

Static Public Member Functions

static Isomorphism< dim > * identity (unsigned nSimplices)
 Returns the identity isomorphism for the given number of simplices. More...
 
static Isomorphism< dim > * random (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_
 Stores the simplex of the destination triangulation that each simplex of the source triangulation maps to. More...
 
NPerm< dim+1 > * facetPerm_
 The permutation applied to the facets of each source simplex. More...
 

Detailed Description

template<int dim>
class regina::Isomorphism< dim >

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

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

More precisely: An isomorphism consists of (i) a one-to-one map f from the simplices of T to the simplices of U, and (ii) for each simplex S of T, a permutation fS of the facets (0,...,dim) 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 for all types of isomorphism, triangulation U is allowed to contain more simplices than triangulation T.

For Regina's standard dimensions, this template is specialised and offers some extra functionality. In order to use these specialised classes, you will need to include the corresponding headers (e.g., dim2/dim2isomorphism.h for dim = 2, or triangulation/nisomorphism.h for dim = 3). For convenience, there are typedefs available for these specialised classes (such as Dim2Isomorphism and NIsomorphism respectively).

Python:
Python does not support templates. Instead this class can be used by appending the dimension as a suffix (e.g., Isomorphism2 and Isomorphism3 for dimensions 2 and 3). The typedefs mentioned above for standard dimensions (e.g., Dim2Isomorphism and NIsomorphism) are also available.
Template Parameters
dimThe dimension of the underlying triangulation. This must be between 2 and 15 inclusive.

Constructor & Destructor Documentation

§ Isomorphism() [1/2]

template<int dim>
regina::Isomorphism< dim >::Isomorphism ( unsigned  nSimplices)
inline

Creates a new isomorphism with no initialisation.

The images of the simplices and their vertices must be explicitly set using simpImage() and facetPerm().

Python:
Not present.
Parameters
nSimplicesthe number of simplices in the source triangulation associated with this isomorphism. This is allowed to be zero.

§ Isomorphism() [2/2]

template<int dim>
regina::Isomorphism< dim >::Isomorphism ( const Isomorphism< dim > &  copy)
inline

Creates a copy of the given isomorphism.

Parameters
copythe isomorphism to copy.

Member Function Documentation

§ apply()

template<int dim>
Triangulation< dim > * regina::detail::IsomorphismBase< dim >::apply ( const Triangulation< dim > *  original) const
inherited

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

An isomorphism represents a combinatorial map from a triangulation T to a triangulation U. This routine treats the given triangulation as the domain T, and returns the corresponding range U. The given triangulation T is not modified in any way.

In more detail: A new triangulation 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 will be combinatorially identical triangulations, and this isomorphism describes the mapping from the simplices of T and their facets to the simplices of U and their 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 full 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 size() for this isomorphism.
The simplex images are precisely 0,1,...,size()-1 in some order (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 new isomorphic triangulation, or 0 if a problem was encountered (i.e., an unmet precondition was noticed).

§ applyInPlace()

template<int dim>
void regina::detail::IsomorphismBase< dim >::applyInPlace ( Triangulation< dim > *  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 in-place.

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 full 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 size() for this isomorphism.
The simplex images are precisely 0,1,...,size()-1 in some order (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.

§ detail()

std::string regina::Output< IsomorphismBase< dim > , false >::detail ( ) const
inherited

Returns a detailed text representation of this object.

This text may span many lines, and should provide the user with all the information they could want. It should be human-readable, should not contain extremely long lines (which cause problems for users reading the output in a terminal), and should end with a final newline. There are no restrictions on the underlying character set.

Returns
a detailed text representation of this object.

§ facetPerm() [1/2]

template<int dim>
NPerm< dim+1 > & regina::detail::IsomorphismBase< dim >::facetPerm ( unsigned  sourceSimp)
inlineinherited

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. 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 size()-1 inclusive.
Returns
a read-write reference to the permutation applied to the facets of the source simplex.

§ facetPerm() [2/2]

template<int dim>
NPerm< dim+1 > regina::detail::IsomorphismBase< dim >::facetPerm ( unsigned  sourceSimp) const
inlineinherited

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 size()-1 inclusive.
Returns
the permutation applied to the facets of the source simplex.

§ getSourceSimplices()

template<int dim>
unsigned regina::detail::IsomorphismBase< dim >::getSourceSimplices ( ) const
inlineinherited

A deprecated alias for size(), which returns the number of simplices in the source triangulation associated with this isomorphism.

Deprecated:
Simply call size() instead.
Returns
the number of simplices in the source triangulation.

§ identity()

template<int dim>
Isomorphism< dim > * regina::detail::IsomorphismBase< dim >::identity ( unsigned  nSimplices)
inlinestaticinherited

Returns the identity isomorphism for the given number of simplices.

This isomorphism sends every simplex and every vertex to itself.

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

Parameters
nSimplicesthe number of simplices that the new isomorphism should operate upon.
Returns
the newly constructed identity isomorphism.

§ isIdentity()

template<int dim>
bool regina::detail::IsomorphismBase< 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.

§ operator[]()

template<int dim>
FacetSpec< dim > regina::detail::IsomorphismBase< dim >::operator[] ( const FacetSpec< dim > &  source) const
inlineinherited

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

This operator returns by value: it 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 size() simplices in the source triangulation.
Returns
the image of the source simplex facet under this isomorphism.

§ random()

template<int dim>
Isomorphism< dim > * regina::detail::IsomorphismBase< 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.

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.

§ simpImage() [1/2]

template<int dim>
int & regina::detail::IsomorphismBase< dim >::simpImage ( unsigned  sourceSimp)
inlineinherited

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

Python:
This is not available for Python users. However, the read-only version of this routine is.
Parameters
sourceSimpthe index of the source simplex; this must be between 0 and size()-1 inclusive.
Returns
a reference to the index of the destination simplex that the source simplex maps to.

§ simpImage() [2/2]

template<int dim>
int regina::detail::IsomorphismBase< dim >::simpImage ( unsigned  sourceSimp) const
inlineinherited

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

Parameters
sourceSimpthe index of the source simplex; this must be between 0 and size()-1 inclusive.
Returns
the index of the destination simplex that the source simplex maps to.

§ size()

template<int dim>
unsigned regina::detail::IsomorphismBase< dim >::size ( ) const
inlineinherited

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.

§ str()

std::string regina::Output< IsomorphismBase< dim > , false >::str ( ) const
inherited

Returns a short text representation of this object.

This text should be human-readable, should fit on a single line, and should not end with a newline. Where possible, it should use plain ASCII characters.

Python:
In addition to str(), this is also used as the Python "stringification" function __str__().
Returns
a short text representation of this object.

§ toString()

REGINA_DEPRECATED std::string regina::Output< IsomorphismBase< dim > , false >::toString ( ) const
inherited

A deprecated alias for str().

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

§ toStringLong()

REGINA_DEPRECATED std::string regina::Output< IsomorphismBase< dim > , false >::toStringLong ( ) const
inherited

A deprecated alias for detail().

Deprecated:
This routine has (at long last) been deprecated; use the simpler-to-type detail() instead.
Returns
a long text representation of this object.

§ utf8()

std::string regina::Output< IsomorphismBase< dim > , false >::utf8 ( ) const
inherited

Returns a short text representation of this object using unicode characters.

Like str(), this text should be human-readable, should fit on a single line, and should not end with a newline. In addition, it may use unicode characters to make the output more pleasant to read. This string will be encoded in UTF-8.

Returns
a short text representation of this object.

§ writeTextLong()

template<int dim>
void regina::detail::IsomorphismBase< dim >::writeTextLong ( std::ostream &  out) const
inlineinherited

Writes a detailed text representation of this object to the given output stream.

Python:
Not present.
Parameters
outthe output stream to which to write.

§ writeTextShort()

template<int dim>
void regina::detail::IsomorphismBase< dim >::writeTextShort ( std::ostream &  out) const
inlineinherited

Writes a short text representation of this object to the given output stream.

Python:
Not present.
Parameters
outthe output stream to which to write.

Member Data Documentation

§ facetPerm_

template<int dim>
NPerm<dim+1>* regina::detail::IsomorphismBase< dim >::facetPerm_
protectedinherited

The permutation applied to the facets of each source simplex.

This array has size nSimplices_.

§ nSimplices_

template<int dim>
unsigned regina::detail::IsomorphismBase< dim >::nSimplices_
protectedinherited

The number of simplices in the source triangulation.

§ simpImage_

template<int dim>
int* regina::detail::IsomorphismBase< dim >::simpImage_
protectedinherited

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

This array has size nSimplices_.


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

Copyright © 1999-2016, 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@maths.uq.edu.au).