regina::NGenericIsomorphism< dim > Class Template Reference
Generic code

A dimension-agnostic base class that represents a combinatorial isomorphism from one dim-manifold triangulation into another. More...

`#include <generic/ngenericisomorphism.h>`

Inheritance diagram for regina::NGenericIsomorphism< dim >:

## 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

| NGenericIsomorphism (unsigned nSimplices)
| Creates a new isomorphism with no initialisation. More...
| NGenericIsomorphism (const NGenericIsomorphism &cloneMe)
| Creates a new isomorphism identical to the given isomorphism. More...
| ~NGenericIsomorphism ()
| Destroys 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...
Perm & | 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...
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...
Triangulation * | apply (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 Isomorphism * | 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_
| The simplex of the destination triangulation that each simplex of the source triangulation maps to. More...
Perm * | facetPerm_
| The permutation applied to the facets of each source simplex. More...

## Detailed Description

### template<int dim>
class regina::NGenericIsomorphism< dim >

A dimension-agnostic base class that represents a combinatorial isomorphism from one dim-manifold triangulation into another.

Each dimension that Regina works with (2, 3 and 4) offers its own subclass with richer functionality; users typically do not need to work with this template base class directly.

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 f_S of the facets (0,...,dim) of S, for which the following condition holds:

- If facet k of simplex S and facet k' of simplex S' are identified in T, then facet f_S(k) of f(S) and facet f_S'(k') of f(S') are identified in U. Moreover, their gluing is consistent with the facet/vertex permutations; that is, there is a commutative square involving the gluing maps in T and U and the permutations f_S and f_S'.

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

- If facet x is a boundary facet of T then facet f(x) is a boundary facet of U.

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

Precondition
  The dimension argument dim is either 2, 3 or 4.

Python:
  Not present, though the dimension-specific subclasses (such as NIsomorphism and Dim4Isomorphism) are available for Python users.

## Member Typedef Documentation

template<int dim>

typedef DimTraits<dim>::Isomorphism regina::NGenericIsomorphism< dim >::Isomorphism

The isomorphism class used by triangulations of this specific dimension.

Typically this is a subclass of NGenericIsomorphism<dim>.

template<int dim>

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

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

template<int dim>

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

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

template<int dim>

typedef DimTraits<dim>::Triangulation regina::NGenericIsomorphism< dim >::Triangulation

The triangulation class specific to this dimension.

## Constructor & Destructor Documentation

template<int dim>

regina::NGenericIsomorphism< dim >::NGenericIsomorphism | ( | unsigned | nSimplices | ) |

inline

Creates a new isomorphism with no initialisation.

Parameters

  nSimplices | the number of simplices in the source triangulation associated with this isomorphism; this may be zero.

template<int dim>

regina::NGenericIsomorphism< dim >::NGenericIsomorphism | ( | const NGenericIsomorphism< dim > & | cloneMe | ) |

Creates a new isomorphism identical to the given isomorphism.

Parameters

  cloneMe | the isomorphism upon which to base the new isomorphism.

template<int dim>

regina::NGenericIsomorphism< dim >::~NGenericIsomorphism | ( |  | ) |

inline

Destroys this isomorphism.

## Member Function Documentation

template<int dim>

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

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

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

template<int dim>

void regina::NGenericIsomorphism< dim >::applyInPlace | ( | Triangulation * | 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 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

  tri | the 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.

template<int dim>

NGenericIsomorphism< dim >::Perm & regina::NGenericIsomorphism< dim >::facetPerm | ( | unsigned | sourceSimp | ) |

inline

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

  sourceSimp | the 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.

template<int dim>

NGenericIsomorphism< dim >::Perm regina::NGenericIsomorphism< dim >::facetPerm | ( | unsigned | sourceSimp | ) | const

inline

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

  sourceSimp | the 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.

template<int dim>

unsigned regina::NGenericIsomorphism< dim >::getSourceSimplices | ( |  | ) | const

inline

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.

template<int dim>

bool regina::NGenericIsomorphism< dim >::isIdentity | ( |  | ) | const

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.

template<int dim>

NFacetSpec< dim > regina::NGenericIsomorphism< dim >::operator[] | ( | const NFacetSpec< dim > & | source | ) | const

inline

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

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

template<int dim>

static Isomorphism* regina::NGenericIsomorphism< dim >::random | ( | unsigned | nSimplices | ) |

static

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

  nSimplices | the number of simplices that the new isomorphism should operate upon.

Returns
  the newly constructed random isomorphism.

template<int dim>

int & regina::NGenericIsomorphism< dim >::simpImage | ( | unsigned | sourceSimp | ) |

inline

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

  sourceSimp | the 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.

template<int dim>

int regina::NGenericIsomorphism< dim >::simpImage | ( | unsigned | sourceSimp | ) | const

inline

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

Parameters

  sourceSimp | the 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

inline inherited

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

inline inherited

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.

template<int dim>

void regina::NGenericIsomorphism< dim >::writeTextLong | ( | std::ostream & | out | ) | const

virtual

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

  out | the output stream to which to write.

Reimplemented from regina::ShareableObject.

template<int dim>

void regina::NGenericIsomorphism< dim >::writeTextShort | ( | std::ostream & | out | ) | const

virtual

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

  out | the output stream to which to write.

Implements regina::ShareableObject.

## Member Data Documentation

template<int dim>

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

protected

The permutation applied to the facets of each source simplex.

template<int dim>

unsigned regina::NGenericIsomorphism< dim >::nSimplices_

protected

The number of simplices in the source triangulation.

template<int dim>

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

protected

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:

- generic/ngenericisomorphism.h

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