Regina Calculation Engine
Public Member Functions | List of all members
regina::NHomGroupPresentation Class Reference

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

#include <algebra/nhomgrouppresentation.h>

Inheritance diagram for regina::NHomGroupPresentation:
regina::ShareableObject regina::boost::noncopyable

Public Member Functions

 NHomGroupPresentation (const NGroupPresentation &domain, const NGroupPresentation &range, const std::vector< NGroupExpression > &map)
 Creates a new homomorphism from the given data. More...
 
 NHomGroupPresentation (const NGroupPresentation &domain, const NGroupPresentation &range, const std::vector< NGroupExpression > &map, const std::vector< NGroupExpression > &inv)
 Creates a declared isomorphism from the given data. More...
 
 NHomGroupPresentation (const NGroupPresentation &groupForIdentity)
 Creates a new identity homomorphism for the given group. More...
 
 NHomGroupPresentation (const NHomGroupPresentation &cloneMe)
 Creates a clone of the given group presentation. More...
 
 ~NHomGroupPresentation ()
 Destroys the group homomorphism. More...
 
const NGroupPresentationgetDomain () const
 The domain of the map. More...
 
const NGroupPresentationgetRange () const
 The range of the map. More...
 
bool knowsInverse () const
 Returns whether or not this is a declared isomorphism. More...
 
NGroupExpression evaluate (const NGroupExpression &arg) const
 Evaluate the homomorphism at an element of the domain. More...
 
NGroupExpression evaluate (unsigned long i) const
 Evaluate the homomorphism at a generator of the domain. More...
 
NGroupExpression invEvaluate (const NGroupExpression &arg) const
 Evaluate the isomorphisms's inverse at an element of the range. More...
 
NGroupExpression invEvaluate (unsigned long i) const
 Evaluate the isomorphism at a generator of the range. More...
 
bool intelligentSimplify ()
 Simultaneously simplifies: More...
 
bool intelligentNielsen ()
 Simplifies the domain and range using only Nielsen moves, keeping track of the resulting map in the progress. More...
 
bool smallCancellation ()
 Simplifies the domain and range using only small cancellation theory. More...
 
std::auto_ptr
< NHomGroupPresentation
composeWith (const NHomGroupPresentation &input) const
 Composes this homomorphism with the given input 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...
 
std::auto_ptr
< NHomMarkedAbelianGroup
markedAbelianisation () const
 Computes the induced map on the abelianizations of the domain and range. 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...
 

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 NHomGroupPresentation(const NGroupPresentation&, const NGroupPresentation&, const std::vector<NGroupExpression>&, const std::vector<NGroupExpression>&).

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.

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

regina::NHomGroupPresentation::NHomGroupPresentation ( const NGroupPresentation domain,
const NGroupPresentation range,
const std::vector< NGroupExpression > &  map 
)
inline

Creates a new homomorphism from the given data.

Python:
Not present.
Parameters
domainthe domain of the homomorphism.
rangethe range of the homomorphism.
mapa 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 range.
Python:
Not present.
regina::NHomGroupPresentation::NHomGroupPresentation ( const NGroupPresentation domain,
const NGroupPresentation range,
const std::vector< NGroupExpression > &  map,
const std::vector< NGroupExpression > &  inv 
)
inline

Creates a declared isomorphism from the given data.

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

Precondition
The argument inv is indeed the inverse of map.
Python:
Not present.
Parameters
domainthe domain of the homomorphism.
rangethe range of the homomorphism.
mapa 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 range.
inva vector of length k where k is the number of generators of the range, and where the inverse homomorphism sends the ith generator of the range to the element inv[i] of the domain.
regina::NHomGroupPresentation::NHomGroupPresentation ( const NGroupPresentation groupForIdentity)

Creates a new identity homomorphism for the given group.

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

Parameters
groupForIdentityboth the range and domain of the new identity homomorphism.
regina::NHomGroupPresentation::NHomGroupPresentation ( const NHomGroupPresentation cloneMe)
inline

Creates a clone of the given group presentation.

Parameters
cloneMethe presentation to clone.
regina::NHomGroupPresentation::~NHomGroupPresentation ( )
inline

Destroys the group homomorphism.

Member Function Documentation

std::auto_ptr<NHomGroupPresentation> regina::NHomGroupPresentation::composeWith ( const NHomGroupPresentation input) const

Composes this homomorphism with the given input homomorphism.

Evaluating the composition on some group element x is the same as evaluating this(input(x)). In other words, in this composition, input 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 range of input must be the same as the domain of this homomorphism.
Parameters
inputthe homomorphism to compose with this.
Returns
the composition of both homomorphisms.
std::string regina::ShareableObject::detail ( ) const
inherited

Returns the output from writeTextLong() as a string.

Returns
a long text representation of this object.
NGroupExpression regina::NHomGroupPresentation::evaluate ( const NGroupExpression arg) const

Evaluate the homomorphism at an element of the domain.

Parameters
argan element of the domain.
Returns
the image of this element in the range.
NGroupExpression regina::NHomGroupPresentation::evaluate ( unsigned long  i) const
inline

Evaluate the homomorphism at a generator of the domain.

Parameters
ithe index of a generator in the domain.
Returns
the image of the ith generator in the range.
const NGroupPresentation & regina::NHomGroupPresentation::getDomain ( ) const
inline

The domain of the map.

Returns
a reference to the domain.
const NGroupPresentation & regina::NHomGroupPresentation::getRange ( ) const
inline

The range of the map.

Returns
a reference to the range.
bool regina::NHomGroupPresentation::intelligentNielsen ( )

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

Returns
true if and only if either presentation was changed.
bool regina::NHomGroupPresentation::intelligentSimplify ( )

Simultaneously simplifies:

  • the presentation of the domain;
  • the presentation of the range;
  • the description of the map.

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

Returns
true if the presentations or map have changed.
bool regina::NHomGroupPresentation::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 NHomGroupPresentation 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).
NGroupExpression regina::NHomGroupPresentation::invEvaluate ( const NGroupExpression arg) const

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

Precondition
This homomorphism is in fact a declared isomorphism. See the NHomGroupPresentation class notes for details on what this means.
Parameters
argan element of the range.
Returns
the image of this element in the domain.
NGroupExpression regina::NHomGroupPresentation::invEvaluate ( unsigned long  i) const
inline

Evaluate the isomorphism at a generator of the range.

Precondition
This homomorphism is in fact a declared isomorphism. See the NHomGroupPresentation class notes for details on what this means.
Parameters
ithe index of a generator in the range.
Returns
the image of this generator in the domain.
bool regina::NHomGroupPresentation::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 NHomGroupPresentation class notes for details.

Returns
true if and only if this is a declared isomorphism, i.e, the inverse map was explicitly provided.
std::auto_ptr< NHomMarkedAbelianGroup > regina::NHomGroupPresentation::markedAbelianisation ( ) const

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

Returns
the induced map on the abelianizations.
bool regina::NHomGroupPresentation::smallCancellation ( )

Simplifies the domain and range using only small cancellation theory.

Returns
true if and only if either presentation was changed.
std::string regina::ShareableObject::str ( ) const
inherited

Returns the output from writeTextShort() as a string.

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

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

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

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

Deprecated:
This routine has (at long last) been deprecated; use the simpler-to-type detail() instead.
Returns
a long text representation of this object.
bool regina::NHomGroupPresentation::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 range.

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.
bool regina::NHomGroupPresentation::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 range.

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 NHomGroupPresentation 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.
void regina::NHomGroupPresentation::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
outthe output stream to which to write.

Reimplemented from regina::ShareableObject.

void regina::NHomGroupPresentation::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
outthe output stream to which to write.

Implements regina::ShareableObject.


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

Copyright © 1999-2014, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@debian.org).