Represents a homomorphism between groups which are described via finite presentations. More...

#include <algebra/homgrouppresentation.h>

Inheritance diagram for regina::HomGroupPresentation:

Public Member Functions
	HomGroupPresentation (GroupPresentation domain, GroupPresentation codomain, std::vector< GroupExpression > map)
	Creates a new homomorphism from the given data. More...

	HomGroupPresentation (GroupPresentation domain, GroupPresentation codomain, std::vector< GroupExpression > map, std::vector< GroupExpression > inv)
	Creates a declared isomorphism from the given data. More...

	HomGroupPresentation (const GroupPresentation &groupForIdentity)
	Creates a new identity homomorphism for the given group. More...

	HomGroupPresentation (const HomGroupPresentation &src)=default
	Creates a clone of the given homomorphism. More...

	HomGroupPresentation (HomGroupPresentation &&src) noexcept=default
	Moves the contents of the given homomorphism into this new homomorphism. More...

HomGroupPresentation &	operator= (const HomGroupPresentation &)=default
	Sets this to be a clone of the given homomorphism. More...

HomGroupPresentation &	operator= (HomGroupPresentation &&) noexcept=default
	Moves the contents of the given homomorphism to this homomorphism. More...

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

bool	operator== (const HomGroupPresentation &other) const
	Determines whether this and the given homomorphism have identical presentations. More...

bool	operator!= (const HomGroupPresentation &other) const
	Determines whether this and the given homomorphism do not have identical presentations. More...

const GroupPresentation &	domain () const
	The domain of the map. More...

const GroupPresentation &	codomain () const
	The codomain of the map. More...

bool	knowsInverse () const
	Returns whether or not this is a declared isomorphism. More...

GroupExpression	evaluate (GroupExpression arg) const
	Evaluate the homomorphism at an element of the domain. More...

GroupExpression	evaluate (unsigned long i) const
	Evaluate the homomorphism at a generator of the domain. More...

GroupExpression	invEvaluate (GroupExpression arg) const
	Evaluate the isomorphisms's inverse at an element of the codomain. More...

GroupExpression	invEvaluate (unsigned long i) const
	Evaluate the isomorphism at a generator of the codomain. More...

bool	intelligentSimplify ()
	Simultaneously simplifies: More...

bool	intelligentNielsen ()
	Simplifies the domain and codomain using only Nielsen moves, keeping track of the resulting map in the progress. More...

bool	smallCancellation ()
	Simplifies the domain and codomain using only small cancellation theory. More...

HomGroupPresentation	operator* (const HomGroupPresentation &rhs) const
	Composes this homomorphism with the given homomorphism. More...

HomGroupPresentation	operator* (HomGroupPresentation &&rhs) const
	Composes this homomorphism with the given homomorphism. More...

HomGroupPresentation	composeWith (const HomGroupPresentation &rhs) const
	Deprecated routine that composes this homomorphism with the given homomorphism. More...

bool	invert ()
	Inverts the homomorphism. More...

bool	verify () const
	Verifies the map is a valid homomorphism. More...

bool	verifyIsomorphism () const
	Attempts to verify that a declared isomorphism is, indeed, an isomorphism. More...

HomMarkedAbelianGroup	markedAbelianisation () const
	Computes the induced map on the abelianizations of the domain and codomain. 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...

Detailed Description

Represents a homomorphism between groups which are described via finite presentations.

Some homomorphisms may be declared isomorphisms. This means that the user (or some other function in Regina) has proven that this is an isomorphism and has explicitly provided the inverse map. To provide the inverse map, you should call the four-argument constructor HomGroupPresentation(const GroupPresentation&, const GroupPresentation&, const std::vector<GroupExpression>&, const std::vector<GroupExpression>&).

You can test for a declared isomorphism by calling knowsInverse(). Even if a homomorphism is not a declared isomorphism, it might still be an isomorphism; this just means that no inverse map was explicitly provided.

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.

Warning: The API for this class has not yet been finalised. This means that the class interface may change in new versions of Regina, without maintaining backward compatibility. If you use this class directly in your own code, please watch the detailed changelogs upon new releases to see if you need to make changes to your code.

Todo:: Add a routine to attempt to verify validity of homomorphism.

Constructor & Destructor Documentation

◆ HomGroupPresentation() [1/5]

regina::HomGroupPresentation::HomGroupPresentation	(	GroupPresentation	domain,
		GroupPresentation	codomain,
		std::vector< GroupExpression >	map
	)

inline

Creates a new homomorphism from the given data.

Parameters

domain	the domain of the homomorphism.
codomain	the codomain of the homomorphism.
map	a vector of length g, where g is the number of generators of the domain, and where this homomorphism sends the ith generator of the domain to the element `map[i]` of the codomain.

◆ HomGroupPresentation() [2/5]

regina::HomGroupPresentation::HomGroupPresentation	(	GroupPresentation	domain,
		GroupPresentation	codomain,
		std::vector< GroupExpression >	map,
		std::vector< GroupExpression >	inv
	)

inline

Creates a declared isomorphism from the given data.

Here you must provide both a map from the domain to codomain, and the inverse map from the codomain to domain.

Precondition: The argument inv is indeed the inverse of map.

Parameters

domain	the domain of the homomorphism.
codomain	the codomain of the homomorphism.
map	a vector of length g, where g is the number of generators of the domain, and where this homomorphism sends the ith generator of the domain to the element `map[i]` of the codomain.
inv	a vector of length k where k is the number of generators of the codomain, and where the inverse homomorphism sends the ith generator of the codomain to the element `inv[i]` of the domain.

◆ HomGroupPresentation() [3/5]

regina::HomGroupPresentation::HomGroupPresentation ( const GroupPresentation & groupForIdentity )

Creates a new identity homomorphism for the given group.

This will be a declared isomorphism (see the HomGroupPresentation class notes for details).

Parameters

groupForIdentity both the domain and codomain of the new identity homomorphism.

◆ HomGroupPresentation() [4/5]

regina::HomGroupPresentation::HomGroupPresentation ( const HomGroupPresentation & src )

default

Creates a clone of the given homomorphism.

◆ HomGroupPresentation() [5/5]

regina::HomGroupPresentation::HomGroupPresentation ( HomGroupPresentation && src )

defaultnoexcept

Moves the contents of the given homomorphism into this new homomorphism.

This is a fast (constant time) operation.

The homomorphism that was passed will no longer be usable.

Member Function Documentation

◆ codomain()

const GroupPresentation & regina::HomGroupPresentation::codomain ( ) const

inline

The codomain of the map.

Returns: a reference to the codomain.

◆ composeWith()

HomGroupPresentation regina::HomGroupPresentation::composeWith ( const HomGroupPresentation & rhs ) const

inline

Deprecated routine that composes this homomorphism with the given homomorphism.

Deprecated:: Instead of a.composeWith(b), use the multiplication operator a * b.

Precondition: the codomain of rhs must be the same as the domain of this homomorphism.

Parameters

rhs	the homomorphism to compose this with.

Returns: the composition of both homomorphisms.

◆ detail()

std::string regina::Output< HomGroupPresentation , 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.

◆ domain()

const GroupPresentation & regina::HomGroupPresentation::domain ( ) const

inline

The domain of the map.

Returns: a reference to the domain.

◆ evaluate() [1/2]

GroupExpression regina::HomGroupPresentation::evaluate ( GroupExpression arg ) const

inline

Evaluate the homomorphism at an element of the domain.

Parameters

arg	an element of the domain.

Returns: the image of this element in the codomain.

◆ evaluate() [2/2]

GroupExpression regina::HomGroupPresentation::evaluate ( unsigned long i ) const

inline

Evaluate the homomorphism at a generator of the domain.

Parameters

i	the index of a generator in the domain.

Returns: the image of the ith generator in the codomain.

◆ intelligentNielsen()

bool regina::HomGroupPresentation::intelligentNielsen ( )

Simplifies the domain and codomain using only Nielsen moves, keeping track of the resulting map in the progress.

Returns: true if and only if either presentation and/or the map was changed.

◆ intelligentSimplify()

bool regina::HomGroupPresentation::intelligentSimplify ( )

Simultaneously simplifies:

the presentation of the domain;
the presentation of the codomain;
the description of the map.

Uses the underlying GroupPresentation::intelligentSimplify(). See that routine for details.

Returns: true if and only if either presentation and/or the map was changed.

◆ invert()

bool regina::HomGroupPresentation::invert ( )

Inverts the homomorphism.

This is only possible if the homomorphism is in fact a declared isomorphism (which means that the inverse map is already stored internally). See the HomGroupPresentation class notes for further details on declared isomorphisms.

If this is not a declared isomorphism then this routine will do nothing and simply return false.

This operation is (very) fast constant time.

Returns: true if and only if the inversion operation was successful (i.e., if this is a declared isomorphism).

◆ invEvaluate() [1/2]

GroupExpression regina::HomGroupPresentation::invEvaluate ( GroupExpression arg ) const

inline

Evaluate the isomorphisms's inverse at an element of the codomain.

Precondition: This homomorphism is in fact a declared isomorphism. See the HomGroupPresentation class notes for details on what this means.

Parameters

arg	an element of the codomain.

Returns: the image of this element in the domain.

◆ invEvaluate() [2/2]

GroupExpression regina::HomGroupPresentation::invEvaluate ( unsigned long i ) const

inline

Evaluate the isomorphism at a generator of the codomain.

Precondition: This homomorphism is in fact a declared isomorphism. See the HomGroupPresentation class notes for details on what this means.

Parameters

i	the index of a generator in the codomain.

Returns: the image of this generator in the domain.

◆ knowsInverse()

bool regina::HomGroupPresentation::knowsInverse ( ) const

inline

Returns whether or not this is a declared isomorphism.

A declared isomorphism is a isomorphism for which the user has explicitly provided the inverse map. See the HomGroupPresentation class notes for details.

Returns: true if and only if this is a declared isomorphism, i.e, the inverse map was explicitly provided.

◆ markedAbelianisation()

HomMarkedAbelianGroup regina::HomGroupPresentation::markedAbelianisation ( ) const

Computes the induced map on the abelianizations of the domain and codomain.

Returns: the induced map on the abelianizations.

◆ operator!=()

bool regina::HomGroupPresentation::operator!= ( const HomGroupPresentation & other ) const

inline

Determines whether this and the given homomorphism do not have identical presentations.

This routine does not test whether the two homomorphisms are equal in the sense that each element of the domain maps to the same group element of the codomain - in general this is an undecidable problem.

Instead, this routine tests whether the two homomorphisms map the ith generator of the domain to precisely the same word in the codomain, for each i.

This routine will not test whether the domains and codomains have identical presentations, or whether either homomorphism is declared to be an isomorphism. However, if the two domains have different numbers of generators then the two homomorphisms will compare as not equal (since it will be impossible to compare the words that the corresponding generators map to).

Parameters

other the homomorphism to compare with this.

Returns: true if and only if this and the given homomorphisms do not have identical presentations.

◆ operator*() [1/2]

HomGroupPresentation regina::HomGroupPresentation::operator* ( const HomGroupPresentation & rhs ) const

Composes this homomorphism with the given homomorphism.

Evaluating the composition on some group element x is the same as evaluating this(rhs(x)). In other words, in this composition, rhs is evaluated first and then the output of that is evaluated by this homomorphism.

If both of the given homomorphisms are declared isomorphisms, then the return value will be a declared isomoprhism also.

Precondition: the codomain of rhs must be the same as the domain of this homomorphism.

Parameters

rhs	the homomorphism to compose this with.

Returns: the composition of both homomorphisms.

◆ operator*() [2/2]

HomGroupPresentation regina::HomGroupPresentation::operator* ( HomGroupPresentation && rhs ) const

Composes this homomorphism with the given homomorphism.

Evaluating the composition on some group element x is the same as evaluating this(rhs(x)). In other words, in this composition, rhs is evaluated first and then the output of that is evaluated by this homomorphism.

If both of the given homomorphisms are declared isomorphisms, then the return value will be a declared isomoprhism also.

Precondition: the codomain of rhs must be the same as the domain of this homomorphism.

Parameters

rhs	the homomorphism to compose this with.

Returns: the composition of both homomorphisms.

◆ operator=() [1/2]

HomGroupPresentation & regina::HomGroupPresentation::operator= ( const HomGroupPresentation & )

default

Sets this to be a clone of the given homomorphism.

Returns: a reference to this homomorphism.

◆ operator=() [2/2]

HomGroupPresentation & regina::HomGroupPresentation::operator= ( HomGroupPresentation && )

defaultnoexcept

Moves the contents of the given homomorphism to this homomorphism.

This is a fast (constant time) operation.

The homomorphism that was passed will no longer be usable.

Returns: a reference to this homomorphism.

◆ operator==()

bool regina::HomGroupPresentation::operator== ( const HomGroupPresentation & other ) const

inline

Determines whether this and the given homomorphism have identical presentations.

This routine does not test whether the two homomorphisms are equal in the sense that each element of the domain maps to the same group element of the codomain - in general this is an undecidable problem.

Instead, this routine tests whether the two homomorphisms map the ith generator of the domain to precisely the same word in the codomain, for each i.

This routine will not test whether the domains and codomains have identical presentations, or whether either homomorphism is declared to be an isomorphism. However, if the two domains have different numbers of generators then the two homomorphisms will compare as not equal (since it will be impossible to compare the words that the corresponding generators map to).

Parameters

other the homomorphism to compare with this.

Returns: true if and only if this and the given homomorphisms have identical presentations.

◆ smallCancellation()

bool regina::HomGroupPresentation::smallCancellation ( )

Simplifies the domain and codomain using only small cancellation theory.

Returns: true if and only if either presentation and/or the map was changed.

◆ str()

std::string regina::Output< HomGroupPresentation , 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()

void regina::HomGroupPresentation::swap ( HomGroupPresentation & other )

inlinenoexcept

Swaps the contents of this and the given homomorphism.

Parameters

other the homomorphism whose contents should be swapped with this.

◆ utf8()

std::string regina::Output< HomGroupPresentation , 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.

◆ verify()

bool regina::HomGroupPresentation::verify ( ) const

Verifies the map is a valid homomorphism.

Specifically, this routine runs through all the relators in the domain, evaluates the homomorphism on the relators and checks that they simplify to 1 in the codomain.

This routine does not guarantee a conclusive result (since the word problem is, in general, undecidable). If this routine returns true then this proves that the homomorphism is indeed valid. If this routine returns false, then the result is inconclusive (i.e., it might still be valid but Regina was not able to prove this).

This routine is intended for sanity checking only: any homomorphism that you construct in Regina should always be valid in this sense.

Returns: true if Regina is able to verify that this is a homomorphism, or false if the result is inconclusive.

◆ verifyIsomorphism()

bool regina::HomGroupPresentation::verifyIsomorphism ( ) const

Attempts to verify that a declared isomorphism is, indeed, an isomorphism.

This routine works by attempting to verify that f^-1(f(x))x^-1 simplifes to 1 for all generators x in the domain, and likewise for the codomain.

This routine does not guarantee a conclusive result. If this routine returns true then this proves that this is indeed an isomorphism. If this routine returns false then the result is inconclusive (i.e., it might still be an isomorphism but Regina was not able to prove this).

You probably only want to run this on good presentations for small cancellation theory - an automorphism of a poorly-presented group likely will not be noticed.

This routine is intended for sanity checking only: any homomorphism that you construct as a declared isomorphism should always be an isomorphism.

Precondition: This homomorphism is in fact a declared isomorphism. See the HomGroupPresentation class notes for details on what this means.

Returns: true if it is verified that this is an isomorphism, or false if the result is inconclusive.

◆ writeTextLong()

void regina::HomGroupPresentation::writeTextLong ( std::ostream & out ) const

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

void regina::HomGroupPresentation::writeTextShort ( std::ostream & out ) const

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.

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

algebra/homgrouppresentation.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ HomGroupPresentation() [1/5]

◆ HomGroupPresentation() [2/5]

◆ HomGroupPresentation() [3/5]

◆ HomGroupPresentation() [4/5]

◆ HomGroupPresentation() [5/5]

Member Function Documentation

◆ codomain()

◆ composeWith()

◆ detail()

◆ domain()

◆ evaluate() [1/2]

◆ evaluate() [2/2]

◆ intelligentNielsen()

◆ intelligentSimplify()

◆ invert()

◆ invEvaluate() [1/2]

◆ invEvaluate() [2/2]

◆ knowsInverse()

◆ markedAbelianisation()

◆ operator!=()

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ smallCancellation()

◆ str()

◆ swap()

◆ utf8()

◆ verify()

◆ verifyIsomorphism()

◆ writeTextLong()

◆ writeTextShort()