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

#include <triangulation/generic.h>

Inheritance diagram for regina::Isomorphism< dim >:

Public Member Functions
	Isomorphism (size_t nSimplices)
	Creates a new isomorphism with no initialisation. More...

	Isomorphism (const Isomorphism &src)
	Creates a copy of the given isomorphism. More...

	Isomorphism (Isomorphism &&src) noexcept
	Moves the given isomorphism into this new isomorphism. More...

	~Isomorphism ()
	Destroys this isomorphism. More...

Isomorphism &	operator= (const Isomorphism &src)
	Copies the given isomorphism into this isomorphism. More...

Isomorphism &	operator= (Isomorphism &&src) noexcept
	Moves the given isomorphism into this isomorphism. More...

void	swap (Isomorphism &other) noexcept
	Swaps the contents of this and the given isomorphism. More...

size_t	size () const
	Returns the number of simplices in the source triangulation associated with this isomorphism. More...

ssize_t &	simpImage (size_t sourceSimp)
	Returns a read-write reference to the image of the given source simplex under this isomorphism. More...

ssize_t	simpImage (size_t sourceSimp) const
	Determines the image of the given source simplex under this isomorphism. More...

void	setSimpImage (size_t sourceSimp, ssize_t image)
	Python-only routine that sets the image of the given source simplex to the given value under this isomorphism. More...

Perm< dim+1 > &	facetPerm (size_t 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< dim+1 >	facetPerm (size_t sourceSimp) const
	Determines the permutation that is applied to the (dim + 1) facets of the given source simplex under this isomorphism. More...

void	setFacetPerm (size_t sourceSimp, Perm< dim+1 > perm)
	Python-only routine that sets 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 >	operator() (const Triangulation< dim > &tri) const
	Applies this isomorphism to the given triangulation, and returns the result as a new triangulation. More...

FacetSpec< dim >	operator() (const FacetSpec< dim > &f) const
	Returns the image of the given facet-of-simplex under this isomorphism. More...

FacetPairing< dim >	operator() (const FacetPairing< dim > &p) const
	Applies this isomorphism to the given facet pairing, and returns the result as a new facet pairing. More...

Triangulation< dim >	apply (const Triangulation< dim > &tri) const
	Deprecated routine that applies this isomorphism to the given triangulation, and returns the result as a new triangulation. More...

void	applyInPlace (Triangulation< dim > &tri) const
	Deprecated routine that applies this isomorphism to the given triangulation, modifying the given triangulation directly. More...

Isomorphism	operator* (const Isomorphism &rhs) const
	Returns the composition of this isomorphism with the given isomorphism. More...

Isomorphism	operator* (Isomorphism &&rhs) const
	Returns the composition of this isomorphism with the given isomorphism. More...

Isomorphism	inverse () const
	Returns the inverse of this isomorphism. More...

Isomorphism< dim > &	operator++ ()
	A preincrement operator that changes this to be the next isomorphism in an iteration through all possible isomorphisms of this size. More...

Isomorphism< dim >	operator++ (int)
	A postincrement operator that changes this to be the next isomorphism in an iteration through all possible isomorphisms of this size. More...

void	tightEncode (std::ostream &out) const
	Writes the tight encoding of this isomorphism to the given output stream. 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...

bool	operator== (const Isomorphism &other) const
	Determines whether this and the given isomorphism are identical. More...

bool	operator!= (const Isomorphism &other) const
	Determines whether this and the given isomorphism are not identical. 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...

std::string	tightEncoding () const
	Returns the tight encoding of this object. More...

Static Public Member Functions
static Isomorphism	tightDecode (std::istream &input)
	Reconstructs an isomorphism from its given tight encoding. More...

static Isomorphism< dim >	identity (size_t nSimplices)
	Returns the identity isomorphism for the given number of simplices. More...

static Isomorphism< dim >	random (size_t nSimplices, bool even=false)
	Returns a random isomorphism for the given number of simplices. More...

static Isomorphism< dim >	tightDecoding (const std::string &enc)
	Reconstructs an object of type T from its given tight encoding. More...

Protected Attributes
size_t	size_
	The number of simplices in the source triangulation. More...

ssize_t *	simpImage_
	Stores the simplex of the destination triangulation that each simplex of the source triangulation maps to. More...

Perm< 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 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 for all types of isomorphism, triangulation U is allowed to contain more simplices than triangulation T.

This class implements C++ move semantics and adheres to the C++ Swappable requirement. It is designed to avoid deep copies wherever possible, even when passing or returning objects by value.

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

Template Parameters

dim	the dimension of the triangulations that this isomorphism class works with. This must be between 2 and 15 inclusive.

Constructor & Destructor Documentation

◆ Isomorphism() [1/3]

template<int dim>

regina::Isomorphism< dim >::Isomorphism ( size_t 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: For Python users, the images of the simplices and their vertices must be set using setSimpImage() and setFacetPerm() instead.

Parameters

nSimplices the number of simplices in the source triangulation associated with this isomorphism. This is allowed to be zero.

◆ Isomorphism() [2/3]

template<int dim>

regina::Isomorphism< dim >::Isomorphism ( const Isomorphism< dim > & src )

inline

Creates a copy of the given isomorphism.

Parameters

src	the isomorphism to copy.

◆ Isomorphism() [3/3]

template<int dim>

regina::Isomorphism< dim >::Isomorphism ( Isomorphism< dim > && src )

inlinenoexcept

Moves the given isomorphism into this new isomorphism.

This is a fast (constant time) operation.

The isomorphism that is passed (src) will no longer be usable.

Parameters

src	the isomorphism to move.

◆ ~Isomorphism()

template<int dim>

regina::Isomorphism< dim >::~Isomorphism

inline

Destroys this isomorphism.

Member Function Documentation

◆ apply()

template<int dim>

Triangulation< dim > regina::Isomorphism< dim >::apply ( const Triangulation< dim > & tri ) const

inline

Deprecated routine that applies this isomorphism to the given triangulation, and returns the result as a new triangulation.

Deprecated:: If this isomorphism is iso, then this routine is equivalent to calling iso(tri). See the bracket operator for further details.

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

Exceptions

InvalidArgument The number of top-dimensional simplices in the given triangulation is not equal to size() for this isomorphism.

Parameters

tri	the triangulation to which this isomorphism should be applied.

Returns: the new isomorphic triangulation.

◆ applyInPlace()

template<int dim>

void regina::Isomorphism< dim >::applyInPlace ( Triangulation< dim > & tri ) const

inline

Deprecated routine that applies this isomorphism to the given triangulation, modifying the given triangulation directly.

Deprecated:: If this isomorphism is iso, then this routine is equivalent to calling tri = iso(tri). See the bracket operator for further details.

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

Exceptions

InvalidArgument The number of top-dimensional simplices in the given triangulation is not equal to size() for this isomorphism.

Parameters

tri	the triangulation to which this isomorphism should be applied.

◆ detail()

std::string regina::Output< Isomorphism< 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>

Perm< dim+1 > & regina::Isomorphism< dim >::facetPerm ( size_t 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).

If the dimension dim is 2 or 3, then you can also access this permutation through the dimension-specific alias edgePerm() or facePerm() respectively.

Python: Not present. For Python users, facetPerm() is a read-only function that returns by value. To edit the isomorphism, use the Python-only routine setFacetPerm() instead.

Parameters

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

Perm< dim+1 > regina::Isomorphism< dim >::facetPerm ( size_t 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).

If the dimension dim is 2 or 3, then you can also access this permutation through the dimension-specific alias edgePerm() or facePerm() respectively.

Parameters

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

◆ identity()

template<int dim>

Isomorphism< dim > regina::Isomorphism< dim >::identity ( size_t nSimplices )

inlinestatic

Returns the identity isomorphism for the given number of simplices.

This isomorphism sends every simplex and every vertex to itself.

Parameters

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

Returns: the identity isomorphism.

◆ inverse()

template<int dim>

Isomorphism< dim > regina::Isomorphism< dim >::inverse

Returns the inverse of this isomorphism.

Precondition: The destination triangulation has precisely the same number of simplices as the source triangulation. In other words, there are no "gaps" in the simplex images: the values simpImage(0), ..., simpImage(size()-1) must be a permutation of 0, ..., size()-1.

Returns: the inverse isomorphism.

◆ isIdentity()

template<int dim>

bool regina::Isomorphism< dim >::isIdentity

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>

bool regina::Isomorphism< dim >::operator!= ( const Isomorphism< dim > & other ) const

inline

Determines whether this and the given isomorphism are not identical.

Two isomorphisms are considered identical if they act on the same number of top-dimensional simplices, and all destination simplex numbers and facet permutations are the same for both isomorphisms.

In particular it is only the simplex, facet and vertex labels that matter: an isomorphism does not refer to a specific triangulation, and there is no sense in which the two isomorphisms need to act on the same triangulations and/or point to the same destination Simplex objects.

It is safe to compare isomorphisms of different sizes (in which case this routine will return true).

Parameters

other the isomorphism to compare with this.

Returns: true if and only if this and the given isomorphism are not identical.

◆ operator()() [1/3]

template<int dim>

FacetPairing< dim > regina::Isomorphism< dim >::operator() ( const FacetPairing< dim > & p ) const

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

Although the Isomorphism class was designed to represent mappings between isomorphic triangulations, it can just as well describe mappings between isomorphic facet pairings. In particular, if iso represents this isomorphism and if p were the facet pairing of some triangulation tri, then iso(p) would be the facet pairing for the triangulation iso(tri). Of course, this routine works directly with the facet pairing, and does not actually construct any triangulations at all.

This routine behaves correctly even if some facets of p are unmatched (i.e., if p models a triangulation with boundary facets).

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

Exceptions

InvalidArgument The number of top-dimensional simplices described by the given facet pairing is not equal to size() for this isomorphism.

Parameters

p	the facet pairing to which this isomorphism should be applied.

Returns: the new isomorphic facet pairing.

◆ operator()() [2/3]

template<int dim>

FacetSpec< dim > regina::Isomorphism< dim >::operator() ( const FacetSpec< dim > & f ) const

inline

Returns the image of the given facet-of-simplex under this isomorphism.

Specifically:

If f.simp is in the range 0,1,...,size()-1 inclusive (i.e., f denotes a facet of an actual top-dimensional simplex), then this routine will return an object denoting facet facetPerm(f.facet) of simplex simpImage(f.simp).
If f.simp is negative (i.e., f takes a before-the-start value), or if f.simp is at least size() (i.e., f takes a boundary or past-the-end value), then this routine will return f unchanged (but see the precondition below).

Precondition: If this isomorphism maps a smaller triangulation into a larger triangulation (in particular, if the simplex images under this isomorphism are not just some reordering of 0,1,...,size()-1), then f must not denote a boundary or past-the-end value. This is because a boundary or past-the-end value is encoded by using a past-the-end value of FacetSpec::simp. If this isomorphism maps into a larger triangulation then this past-the-end simplex number would need to change, but the isomorphism does not actually know what the new value of FacetSpec::simp should be.

Parameters

f	the facet-of-simplex which should be transformed by this isomorphism.

Returns: the image of f under this isomorphism.

◆ operator()() [3/3]

template<int dim>

Triangulation< dim > regina::Isomorphism< dim >::operator() ( const Triangulation< dim > & tri ) const

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 isomorphic triangulations, and this isomorphism describes the mapping from the simplices of T and their facets to the simplices of U and their facets.

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

Todo:: Lock the topological properties of the underlying manifold, to avoid recomputing them after the isomorphism is applied.

Exceptions

InvalidArgument The number of top-dimensional simplices in the given triangulation is not equal to size() for this isomorphism.

Parameters

tri	the triangulation to which this isomorphism should be applied.

Returns: the new isomorphic triangulation.

◆ operator*() [1/2]

template<int dim>

Isomorphism< dim > regina::Isomorphism< dim >::operator* ( const Isomorphism< dim > & rhs ) const

Returns the composition of this isomorphism with the given isomorphism.

This follows the same order convention as Regina's permutation classes: the composition a * b first applies the right-hand isomorphism b, and then the left-hand isomorphism a.

Precondition: The source triangulation for this isomorphism (the left-hand side) is at least as large as the destination triangulation for rhs (the right-hand side). In other words, the maximum value of rhs.simpImage(i) over all i must be less than this->size().

Returns: the composition of both isomorphisms.

◆ operator*() [2/2]

template<int dim>

Isomorphism< dim > regina::Isomorphism< dim >::operator* ( Isomorphism< dim > && rhs ) const

Returns the composition of this isomorphism with the given isomorphism.

This follows the same order convention as Regina's permutation classes: the composition a * b first applies the right-hand isomorphism b, and then the left-hand isomorphism a.

Precondition: The source triangulation for this isomorphism (the left-hand side) is at least as large as the destination triangulation for rhs (the right-hand side). In other words, the maximum value of rhs.simpImage(i) over all i must be less than this->size().

Returns: the composition of both isomorphisms.

◆ operator++() [1/2]

template<int dim>

Isomorphism< dim > & regina::Isomorphism< dim >::operator++

A preincrement operator that changes this to be the next isomorphism in an iteration through all possible isomorphisms of this size.

The order of iteration is lexicographical, by the sequence of simplex images and then by the sequence of facet permutations. Facet permutations, in turn, are ordered by their indices in the array Perm<dim>::Sn.

In particular, the identity isomorphism is the first in such an iteration. If this isomorphism is the last in such an iteration, then this operator will "wrap around" and set this to the identity.

Precondition: The class Perm<dim+1> supports the preincrement operator; currently this means that dim must be at most 6.

Python: This routine is named inc() since Python does not support the increment operator. Unlike other Regina classes, here inc() wraps the preincrement operator (not the postincrement operator), since the postincrement operator is significantly more expensive. To avoid confusion, the python inc() function returns None (not this isomorphism).

Returns: a reference to this isomorphism after the increment.

◆ operator++() [2/2]

template<int dim>

Isomorphism< dim > regina::Isomorphism< dim >::operator++ ( int )

inline

A postincrement operator that changes this to be the next isomorphism in an iteration through all possible isomorphisms of this size.

The order of iteration is lexicographical, by the sequence of simplex images and then by the sequence of facet permutations. Facet permutations, in turn, are ordered by their indices in the array Perm<dim>::Sn.

In particular, the identity isomorphism is the first in such an iteration. If this isomorphism is the last in such an iteration, then this operator will "wrap around" and set this to the identity.

Warning: Since the postincrement operator returns an isomorphism by value, it is significantly more expensive than the preincrement operator (since it involves a deep copy of a large object). You should use the preincrement operator unless you actually need a copy of the old value of this isomorphism.

Precondition: The class Perm<dim+1> supports the preincrement operator; currently this means that dim must be at most 6.

Python: Not present. The preincrement operator is present in Python as the member function inc(). (Note that this is different from other Regina classes, where inc() typically wraps the postincrement operator instead. See the preincrement documentation for details.)

Returns: a copy of this isomorphism before the increment took place.

◆ operator=() [1/2]

template<int dim>

Isomorphism< dim > & regina::Isomorphism< dim >::operator= ( const Isomorphism< dim > & src )

Copies the given isomorphism into this isomorphism.

It does not matter if this and the given isomorphism use different numbers of simplices; if they do then this isomorphism will be resized as a result.

This operator induces a deep copy of src.

Parameters

src	the isomorphism to copy.

Returns: a reference to this isomorphism.

◆ operator=() [2/2]

template<int dim>

Isomorphism< dim > & regina::Isomorphism< dim >::operator= ( Isomorphism< dim > && src )

noexcept

Moves the given isomorphism into this isomorphism.

This is a fast (constant time) operation.

It does not matter if this and the given isomorphism use different numbers of simplices; if they do then this isomorphism will be resized as a result.

The isomorphism that is passed (src) will no longer be usable.

Parameters

src	the isomorphism to move.

Returns: a reference to this isomorphism.

◆ operator==()

template<int dim>

bool regina::Isomorphism< dim >::operator== ( const Isomorphism< dim > & other ) const

inline

Determines whether this and the given isomorphism are identical.

Two isomorphisms are considered identical if they act on the same number of top-dimensional simplices, and all destination simplex numbers and facet permutations are the same for both isomorphisms.

In particular it is only the simplex, facet and vertex labels that matter: an isomorphism does not refer to a specific triangulation, and there is no sense in which the two isomorphisms need to act on the same triangulations and/or point to the same destination Simplex objects.

It is safe to compare isomorphisms of different sizes (in which case this routine will return false).

Parameters

other the isomorphism to compare with this.

Returns: true if and only if this and the given isomorphism are identical.

◆ operator[]()

template<int dim>

FacetSpec< dim > regina::Isomorphism< dim >::operator[] ( const FacetSpec< dim > & source ) const

inline

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

source the 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::Isomorphism< dim >::random	(	size_t	nSimplices,
		bool	even = `false`
	)

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.

All possible isomorphisms for the given number of simplices are equally likely.

This routine is thread-safe, and uses RandomEngine for its random number generation.

Parameters

nSimplices	the number of simplices that the new isomorphism should operate upon.
even	if `true`, then every simplex will have its vertices permuted with an even permutation. This means that, if the random isomorphism is applied to an oriented triangulation, it will preserve the orientation.

Returns: the new random isomorphism.

◆ setFacetPerm()

template<int dim>

void regina::Isomorphism< dim >::setFacetPerm	(	size_t	sourceSimp,
		Perm< dim+1 >	perm
	)

Python-only routine that sets 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 perm[i] of simplex simpImage(sourceSimp).

If the dimension dim is 2 or 3, then you can also set this permutation through the dimension-specific alias setEdgePerm() or setFacePerm() respectively.

C++: Not present. For C++ users, facetPerm() is used for both reading and writing: just write facetPerm(sourceSimp) = perm.

Parameters

sourceSimp	the index of the source simplex containing the original (dim + 1) facets; this must be between 0 and `size()-1` inclusive.
perm	the new permutation that should be applied to the facets of the source simplex.

◆ setSimpImage()

template<int dim>

void regina::Isomorphism< dim >::setSimpImage	(	size_t	sourceSimp,
		ssize_t	image
	)

Python-only routine that sets the image of the given source simplex to the given value under this isomorphism.

If the dimension dim is 2, 3 or 4, then you can also set this image through the dimension-specific alias setTriImage(), setTetImage() or setPentImage() respectively.

Simplex images are stored using type ssize_t, not size_t, and so you can safely use the special value -1 as a marker for an image that is unknown or not yet initialised.

C++: Not present. For C++ users, simpImage() is used for both reading and writing: just write simpImage(sourceSimp) = image.

Parameters

sourceSimp	the index of the source simplex; this must be between 0 and `size()-1` inclusive.
image	the index of the new destination simplex that the source simplex should map to.

◆ simpImage() [1/2]

template<int dim>

ssize_t & regina::Isomorphism< dim >::simpImage ( size_t sourceSimp )

inline

Returns a read-write reference to the image of the given source simplex under this isomorphism.

If the dimension dim is 2, 3 or 4, then you can also access this image through the dimension-specific alias triImage(), tetImage() or pentImage() respectively.

This image is stored using type ssize_t, not size_t, and so you can safely use the special value -1 as a marker for an image that is unknown or not yet initialised.

Python: Not present. For Python users, simpImage() is a read-only function that returns by value. To edit the isomorphism, use the Python-only routine setSimpImage() instead.

Parameters

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

ssize_t regina::Isomorphism< dim >::simpImage ( size_t sourceSimp ) const

inline

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

If the dimension dim is 2, 3 or 4, then you can also access this image through the dimension-specific alias triImage(), tetImage() or pentImage() respectively.

Parameters

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

size_t regina::Isomorphism< dim >::size

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.

Python: This is also used to implement the Python special method len().

Returns: the number of simplices in the source triangulation.

◆ str()

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

inherited

Returns a short text representation of this object.

This text should be human-readable, should use plain ASCII characters where possible, and should not contain any newlines.

Within these limits, this short text ouptut should be as information-rich as possible, since in most cases this forms the basis for the Python __str__() and __repr__() functions.

Python: The Python "stringification" function __str__() will use precisely this function, and for most classes the Python __repr__() function will incorporate this into its output.

Returns: a short text representation of this object.

◆ swap()

template<int dim>

void regina::Isomorphism< dim >::swap ( Isomorphism< dim > & other )

noexcept

Swaps the contents of this and the given isomorphism.

It does not matter if this and the given isomorphism use different numbers of simplices; if so then they will be adjusted accordingly.

Parameters

other the isomorphism whose contents are to be swapped with this.

◆ tightDecode()

template<int dim>

Isomorphism< dim > regina::Isomorphism< dim >::tightDecode ( std::istream & input )

static

Reconstructs an isomorphism from its given tight encoding.

See the page on tight encodings for details.

The tight encoding will be read from the given input stream. If the input stream contains leading whitespace then it will be treated as an invalid encoding (i.e., this routine will throw an exception). The input routine may contain further data: if this routine is successful then the input stream will be left positioned immediately after the encoding, without skipping any trailing whitespace.

Exceptions

InvalidInput The given input stream does not begin with a tight encoding of an isomorphism on dim-dimensional triangulations.

Python: Not present. Use tightDecoding() instead, which takes a string as its argument.

Parameters

input an input stream that begins with the tight encoding for an isomorphism on dim-dimensional triangulations.

Returns: the isomorphism represented by the given tight encoding.

◆ tightDecoding()

static Isomorphism< dim > regina::TightEncodable< Isomorphism< dim > >::tightDecoding ( const std::string & enc )

inlinestaticinherited

Reconstructs an object of type T from its given tight encoding.

See the page on tight encodings for details.

The tight encoding should be given as a string. If this string contains leading whitespace or any trailing characters at all (including trailing whitespace), then it will be treated as an invalid encoding (i.e., this routine will throw an exception).

Exceptions

InvalidArgument The given string is not a tight encoding of an object of type T.

Parameters

enc	the tight encoding for an object of type T.

Returns: the object represented by the given tight encoding.

◆ tightEncode()

template<int dim>

void regina::Isomorphism< dim >::tightEncode ( std::ostream & out ) const

Writes the tight encoding of this isomorphism to the given output stream.

See the page on tight encodings for details.

Python: Not present. Use tightEncoding() instead, which returns a string.

Parameters

out	the output stream to which the encoded string will be written.

◆ tightEncoding()

std::string regina::TightEncodable< Isomorphism< dim > >::tightEncoding ( ) const

inlineinherited

Returns the tight encoding of this object.

See the page on tight encodings for details.

Exceptions

FailedPrecondition This may be thrown for some classes T if the object is in an invalid state. If this is possible, then a more detailed explanation of "invalid" can be found in the class documentation for T, under the member function T::tightEncode(). See FacetPairing::tightEncode() for an example of this.

Returns: the resulting encoded string.

◆ utf8()

std::string regina::Output< Isomorphism< 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 not contain any newlines, and (within these constraints) should be as information-rich as is reasonable.

Unlike str(), this function may use unicode characters to make the output more pleasant to read. The string that is returned will be encoded in UTF-8.

Returns: a short text representation of this object.

◆ writeTextLong()

template<int dim>

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

inline

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

Python: Not present. Use detail() instead.

Parameters

out	the output stream to which to write.

◆ writeTextShort()

template<int dim>

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

inline

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

Python: Not present. Use str() instead.

Parameters

out	the output stream to which to write.

Member Data Documentation

◆ facetPerm_

template<int dim>

Perm<dim+1>* regina::Isomorphism< dim >::facetPerm_

protected

The permutation applied to the facets of each source simplex.

This array has size size_.

◆ simpImage_

template<int dim>

ssize_t* regina::Isomorphism< dim >::simpImage_

protected

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

This array has size size_.

◆ size_

template<int dim>

size_t regina::Isomorphism< dim >::size_

protected

The number of simplices in the source triangulation.

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

triangulation/cut.h
triangulation/generic/isomorphism.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Isomorphism() [1/3]

◆ Isomorphism() [2/3]

◆ Isomorphism() [3/3]

◆ ~Isomorphism()

Member Function Documentation

◆ apply()

◆ applyInPlace()

◆ detail()

◆ facetPerm() [1/2]

◆ facetPerm() [2/2]

◆ identity()

◆ inverse()

◆ isIdentity()

◆ operator!=()

◆ operator()() [1/3]

◆ operator()() [2/3]

◆ operator()() [3/3]

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator++() [1/2]

◆ operator++() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ operator[]()

◆ random()

◆ setFacetPerm()

◆ setSimpImage()

◆ simpImage() [1/2]

◆ simpImage() [2/2]

◆ size()

◆ str()

◆ swap()

◆ tightDecode()

◆ tightDecoding()

◆ tightEncode()

◆ tightEncoding()

◆ utf8()

◆ writeTextLong()

◆ writeTextShort()

Member Data Documentation

◆ facetPerm_

◆ simpImage_

◆ size_