regina::NHomGroupPresentation Class Reference
Algebraic Structures

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

`#include <algebra/nhomgrouppresentation.h>`

Inheritance diagram for regina::NHomGroupPresentation:

## 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 NGroupPresentation & | getDomain () const
| The domain of the map. More...
const NGroupPresentation & | getRange () 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

  domain | the domain of the homomorphism.
  range | the range 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 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

  domain | the domain of the homomorphism.
  range | the range 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 range.
  inv | a 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

  groupForIdentity | both 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

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

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

  arg | an 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

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

  arg | an 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

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

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.

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

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

  out | the output stream to which to write.

Implements regina::ShareableObject.

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

- algebra/nhomgrouppresentation.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).