Algebraic Structures

## Classes

class | regina::AbelianGroup
| Represents a finitely generated abelian group. More...
struct | regina::GroupExpressionTerm
| Represents a power of a generator in a group presentation. More...
class | regina::GroupExpression
| Represents an expression involving generators from a group presentation or a free group. More...
class | regina::GroupPresentation
| Represents a finite presentation of a group. More...
class | regina::HomGroupPresentation
| Represents a homomorphism between groups which are described via finite presentations. More...
class | regina::MarkedAbelianGroup
| Represents a finitely generated abelian group given by a chain complex. More...
class | regina::HomMarkedAbelianGroup
| Represents a homomorphism of finitely generated abelian groups. More...
class | regina::XMLAbelianGroupReader
| An XML element reader that reads a single abelian group. More...
class | regina::XMLGroupPresentationReader
| An XML element reader that reads a single group presentation. More...

## Typedefs

typedef AbelianGroup | regina::NAbelianGroup
| Deprecated typedef for backward compatibility. More...
typedef GroupExpressionTerm | regina::NGroupExpressionTerm
| Deprecated typedef for backward compatibility. More...
typedef GroupExpression | regina::NGroupExpression
| Deprecated typedef for backward compatibility. More...
typedef GroupPresentation | regina::NGroupPresentation
| Deprecated typedef for backward compatibility. More...
typedef HomGroupPresentation | regina::NHomGroupPresentation
| Deprecated typedef for backward compatibility. More...
typedef MarkedAbelianGroup | regina::NMarkedAbelianGroup
| Deprecated typedef for backward compatibility. More...
typedef HomMarkedAbelianGroup | regina::NHomMarkedAbelianGroup
| Deprecated typedef for backward compatibility. More...

## Functions

| regina::AbelianGroup::AbelianGroup ()
| Creates a new trivial group. More...
| regina::AbelianGroup::AbelianGroup (const AbelianGroup &cloneMe)
| Creates a clone of the given group. More...
| regina::AbelianGroup::AbelianGroup (const MatrixInt &M, const MatrixInt &N)
| Creates an abelian group as the homology of a chain complex. More...
| regina::AbelianGroup::AbelianGroup (const MatrixInt &M, const MatrixInt &N, const Integer &p)
| Creates an abelian group as the homology of a chain complex, using mod-p coefficients. More...
void | regina::AbelianGroup::addRank (int extraRank=1)
| Increments the rank of the group by the given integer. More...
void | regina::AbelianGroup::addTorsionElement (const Integer &degree, unsigned mult=1)
| Adds the given torsion element to the group. More...
void | regina::AbelianGroup::addTorsionElement (unsigned long degree, unsigned mult=1)
| Adds the given torsion element to the group. More...
void | regina::AbelianGroup::addTorsionElements (const std::multiset< Integer > &torsion)
| Adds the given set of torsion elements to this group. More...
void | regina::AbelianGroup::addGroup (const MatrixInt &presentation)
| Adds the abelian group defined by the given presentation to this group. More...
void | regina::AbelianGroup::addGroup (const AbelianGroup &group)
| Adds the given abelian group to this group. More...
unsigned | regina::AbelianGroup::rank () const
| Returns the rank of the group. More...
unsigned | regina::AbelianGroup::torsionRank (const Integer &degree) const
| Returns the rank in the group of the torsion term of given degree. More...
unsigned | regina::AbelianGroup::torsionRank (unsigned long degree) const
| Returns the rank in the group of the torsion term of given degree. More...
size_t | regina::AbelianGroup::countInvariantFactors () const
| Returns the number of invariant factors that describe the torsion elements of this group. More...
const Integer & | regina::AbelianGroup::invariantFactor (size_t index) const
| Returns the given invariant factor describing the torsion elements of this group. More...
bool | regina::AbelianGroup::isTrivial () const
| Determines whether this is the trivial (zero) group. More...
bool | regina::AbelianGroup::isZ () const
| Determines whether this is the infinite cyclic group (Z). More...
bool | regina::AbelianGroup::isZn (unsigned long n) const
| Determines whether this is the non-trivial cyclic group on the given number of elements. More...
bool | regina::AbelianGroup::operator== (const AbelianGroup &other) const
| Determines whether this and the given abelian group are isomorphic. More...
bool | regina::AbelianGroup::operator!= (const AbelianGroup &other) const
| Determines whether this and the given abelian group are non-isomorphic. More...
void | regina::AbelianGroup::writeXMLData (std::ostream &out) const
| Writes a chunk of XML containing this abelian group. More...
void | regina::AbelianGroup::writeTextShort (std::ostream &out, bool utf8=false) const
| Writes a short text representation of this object to the given output stream. More...
void | regina::AbelianGroup::replaceTorsion (const MatrixInt &matrix)
| Replaces the torsion elements of this group with those in the abelian group represented by the given Smith normal form presentation matrix. More...
| regina::GroupExpressionTerm::GroupExpressionTerm ()
| Creates a new uninitialised term. More...
| regina::GroupExpressionTerm::GroupExpressionTerm (unsigned long newGen, long newExp)
| Creates a new term initialised to the given value. More...
| regina::GroupExpressionTerm::GroupExpressionTerm (const GroupExpressionTerm &cloneMe)
| Creates a new term initialised to the given value. More...
GroupExpressionTerm & | regina::GroupExpressionTerm::operator= (const GroupExpressionTerm &cloneMe)
| Makes this term identical to the given term. More...
bool | regina::GroupExpressionTerm::operator== (const GroupExpressionTerm &other) const
| Determines whether this and the given term contain identical data. More...
bool | regina::GroupExpressionTerm::operator!= (const GroupExpressionTerm &other) const
| Determines whether this and the given term do not contain identical data. More...
bool | regina::GroupExpressionTerm::operator< (const GroupExpressionTerm &other) const
| Imposes an ordering on terms. More...
GroupExpressionTerm | regina::GroupExpressionTerm::inverse () const
| Returns the inverse of this term. More...
bool | regina::GroupExpressionTerm::operator+= (const GroupExpressionTerm &other)
| Attempts to merge this term with the given term. More...
std::ostream & | regina::operator<< (std::ostream &out, const GroupExpressionTerm &term)
| Writes the given term to the given output stream. More...
| regina::GroupExpression::GroupExpression ()
| The terms that make up this expression. More...
| regina::GroupExpression::GroupExpression (const GroupExpression &cloneMe)
| Creates a new expression that is a clone of the given expression. More...
| regina::GroupExpression::GroupExpression (const std::string &input, bool *valid=NULL)
| Attempts to interpret the given input string as a word in a group. More...
GroupExpression & | regina::GroupExpression::operator= (const GroupExpression &cloneMe)
| Makes this expression a clone of the given expression. More...
bool | regina::GroupExpression::operator== (const GroupExpression &comp) const
| Equality operator. More...
bool | regina::GroupExpression::operator!= (const GroupExpression &comp) const
| Inequality operator. More...
std::list< GroupExpressionTerm > & | regina::GroupExpression::terms ()
| Returns the list of terms in this expression. More...
const std::list< GroupExpressionTerm > & | regina::GroupExpression::terms () const
| Returns a constant reference to the list of terms in this expression. More...
size_t | regina::GroupExpression::countTerms () const
| Returns the number of terms in this expression. More...
size_t | regina::GroupExpression::wordLength () const
| Returns the length of the word, i.e. More...
bool | regina::GroupExpression::isTrivial () const
| Tests whether this is the trivial (unit) word. More...
void | regina::GroupExpression::erase ()
| Erases all terms from this this word. More...
GroupExpressionTerm & | regina::GroupExpression::term (size_t index)
| Returns the term at the given index in this expression. More...
const GroupExpressionTerm & | regina::GroupExpression::term (size_t index) const
| Returns a constant reference to the term at the given index in this expression. More...
unsigned long | regina::GroupExpression::generator (size_t index) const
| Returns the generator corresonding to the term at the given index in this expression. More...
long | regina::GroupExpression::exponent (size_t index) const
| Returns the exponent corresonding to the term at the given index in this expression. More...
void | regina::GroupExpression::addTermFirst (const GroupExpressionTerm &term)
| Adds the given term to the beginning of this expression. More...
void | regina::GroupExpression::addTermFirst (unsigned long generator, long exponent)
| Adds the given term to the beginning of this expression. More...
void | regina::GroupExpression::addTermLast (const GroupExpressionTerm &term)
| Adds the given term to the end of this expression. More...
void | regina::GroupExpression::addTermLast (unsigned long generator, long exponent)
| Adds the given term to the end of this expression. More...
void | regina::GroupExpression::addTermsFirst (const GroupExpression &word)
| Multiplies this expression on the left by the given word. More...
void | regina::GroupExpression::addTermsLast (const GroupExpression &word)
| Multiplies this expression on the right by the given word. More...
bool | regina::GroupExpression::addStringFirst (const std::string &input)
| Multiplies this expression on the left by the word respresented by the given string. More...
bool | regina::GroupExpression::addStringLast (const std::string &input)
| Multiplies this expression on the right by the word respresented by the given string. More...
void | regina::GroupExpression::cycleRight ()
| Cycles this word by moving the leftmost term around to the rightmost. More...
void | regina::GroupExpression::cycleLeft ()
| Cycles this word by moving the rightmost term around to the leftmost. More...
GroupExpression * | regina::GroupExpression::inverse () const
| Returns a newly created expression that is the inverse of this expression. More...
void | regina::GroupExpression::invert ()
| Inverts this expression. More...
GroupExpression * | regina::GroupExpression::power (long exponent) const
| Returns a newly created expression that is this expression raised to the given power. More...
bool | regina::GroupExpression::simplify (bool cyclic=false)
| Simplifies this expression. More...
bool | regina::GroupExpression::substitute (unsigned long generator, const GroupExpression &expansion, bool cyclic=false)
| Replaces every occurrence of the given generator with the given substite expression. More...
std::list< std::map< unsigned long, GroupExpressionTerm > > | regina::GroupExpression::relabellingsThisToOther (const GroupExpression &other, bool cyclic=false) const
| Determines whether or not one can relabel the generators in this word to obtain the given other word. More...
void | regina::GroupExpression::writeXMLData (std::ostream &out) const
| Writes a chunk of XML containing this expression. More...
std::string | regina::GroupExpression::toTeX () const
| Returns a TeX representation of this expression. More...
void | regina::GroupExpression::writeTeX (std::ostream &out) const
| Writes a TeX represesentation of this expression to the given output stream. More...
void | regina::GroupExpression::writeText (std::ostream &out, bool shortword=false, bool utf8=false) const
| Writes a text representation of this expression to the given output stream, using either numbered generators or alphabetic generators. More...
void | regina::GroupExpression::writeTextShort (std::ostream &out) const
| Writes a short text representation of this object to the given output stream. More...
| regina::GroupPresentation::GroupPresentation ()
| Creates a new presentation with no generators and no relations. More...
| regina::GroupPresentation::GroupPresentation (const GroupPresentation &cloneMe)
| Creates a clone of the given group presentation. More...
| regina::GroupPresentation::GroupPresentation (unsigned long nGens, const std::vector< std::string > &rels)
| Constructor that allows you to directly pass an arbitrary number of relators in string format. More...
| regina::GroupPresentation::~GroupPresentation ()
| Destroys the group presentation. More...
GroupPresentation & | regina::GroupPresentation::operator= (const GroupPresentation &cloneMe)
| Assignment operator. More...
unsigned long | regina::GroupPresentation::addGenerator (unsigned long numToAdd=1)
| Adds one or more generators to the group presentation. More...
void | regina::GroupPresentation::addRelation (GroupExpression *rel)
| Adds the given relation to the group presentation. More...
unsigned long | regina::GroupPresentation::countGenerators () const
| Returns the number of generators in this group presentation. More...
size_t | regina::GroupPresentation::countRelations () const
| Returns the number of relations in this group presentation. More...
const GroupExpression & | regina::GroupPresentation::relation (size_t index) const
| Returns the relation at the given index in this group presentation. More...
bool | regina::GroupPresentation::isValid () const
| Tests whether all of the relations for the group are indeed words in the generators. More...
bool | regina::GroupPresentation::intelligentSimplify ()
| Attempts to simplify the group presentation as intelligently as possible without further input. More...
std::unique_ptr< HomGroupPresentation > | regina::GroupPresentation::intelligentSimplifyDetail ()
| Attempts to simplify the group presentation as intelligently as possible without further input. More...
bool | regina::GroupPresentation::smallCancellation ()
| Attempts to simplify the group presentation using only small cancellation theory. More...
std::unique_ptr< HomGroupPresentation > | regina::GroupPresentation::smallCancellationDetail ()
| Attempts to simplify the group presentation using small cancellation theory. More...
bool | regina::GroupPresentation::simplifyWord (GroupExpression &input) const
| Uses small cancellation theory to reduce the input word, using the current presentation of the group. More...
void | regina::GroupPresentation::proliferateRelators (unsigned long depth=1)
| A routine to help escape local wells when simplifying presentations, which may be useful when small cancellation theory can't find the simplest relators. More...
std::string | regina::GroupPresentation::recogniseGroup (bool moreUtf8=false) const
| Attempts to recognise the group corresponding to this presentation. More...
void | regina::GroupPresentation::writeXMLData (std::ostream &out) const
| Writes a chunk of XML containing this group presentation. More...
size_t | regina::GroupPresentation::relatorLength () const
| The sum of the word lengths of the relators. More...
std::unique_ptr< AbelianGroup > | regina::GroupPresentation::abelianisation () const
| Computes the abelianisation of this group. More...
std::unique_ptr< MarkedAbelianGroup > | regina::GroupPresentation::markedAbelianisation () const
| Computes the abelianisation of this group. More...
bool | regina::GroupPresentation::identifyAbelian () const
| Attempts to determine if the group is abelian. More...
bool | regina::GroupPresentation::nielsenTransposition (unsigned long i, unsigned long j)
| Switches the generators in the presentation indexed by i and j respectively, and recomputes the appropriate presentation. More...
bool | regina::GroupPresentation::nielsenInvert (unsigned long i)
| Replaces a generator in a presentation by its inverse, and recomputes the appropriate presentation. More...
bool | regina::GroupPresentation::nielsenCombine (unsigned long i, unsigned long j, long k, bool rightMult=true)
| Replaces a generator `gi` by either `(gi)(gj)^k` or `(gj)^k(gi)` in the presentation. More...
bool | regina::GroupPresentation::intelligentNielsen ()
| Looks for Nielsen moves that will simplify the presentation. More...
std::unique_ptr< HomGroupPresentation > | regina::GroupPresentation::intelligentNielsenDetail ()
| Looks for Nielsen moves that will simplify the presentation. More...
bool | regina::GroupPresentation::homologicalAlignment ()
| Rewrites the presentation so that generators of the group map to generators of the abelianisation, with any left-over generators mapping to zero (if possible). More...
std::unique_ptr< HomGroupPresentation > | regina::GroupPresentation::homologicalAlignmentDetail ()
| Rewrites the presentation so that generators of the group map to generators of the abelianisation, with any left-over generators mapping to zero (if possible). More...
bool | regina::GroupPresentation::prettyRewriting ()
| An entirely cosmetic re-writing of the presentation, which is fast and superficial. More...
std::unique_ptr< HomGroupPresentation > | regina::GroupPresentation::prettyRewritingDetail ()
| An entirely cosmetic re-writing of the presentation, which is fast and superficial. More...
bool | regina::GroupPresentation::identifySimplyIsomorphicTo (const GroupPresentation &other) const
| Attempts to prove that this and the given group presentation are simply isomorphic. More...
std::string | regina::GroupPresentation::toTeX () const
| Returns a TeX representation of this group presentation. More...
void | regina::GroupPresentation::writeTeX (std::ostream &out) const
| Writes a TeX represesentation of this group presentation to the given output stream. More...
std::string | regina::GroupPresentation::compact () const
| Returns a compact one-line representation of this group presentation, including details of all generators and relations. More...
void | regina::GroupPresentation::writeTextCompact (std::ostream &out) const
| Writes a compact represesentation of this group to the given output stream. More...
void | regina::GroupPresentation::writeTextShort (std::ostream &out) const
| Writes a short text representation of this object to the given output stream. More...
void | regina::GroupPresentation::writeTextLong (std::ostream &out) const
| Writes a detailed text representation of this object to the given output stream. More...
bool | regina::GroupPresentation::NWordSubstitutionData::operator< (const NWordSubstitutionData &other) const
void | regina::GroupPresentation::NWordSubstitutionData::writeTextShort (std::ostream &out) const
| regina::HomGroupPresentation::HomGroupPresentation (const GroupPresentation &domain, const GroupPresentation &range, const std::vector< GroupExpression > &map)
| Creates a new homomorphism from the given data. More...
| regina::HomGroupPresentation::HomGroupPresentation (const GroupPresentation &domain, const GroupPresentation &range, const std::vector< GroupExpression > &map, const std::vector< GroupExpression > &inv)
| Creates a declared isomorphism from the given data. More...
| regina::HomGroupPresentation::HomGroupPresentation (const GroupPresentation &groupForIdentity)
| Creates a new identity homomorphism for the given group. More...
| regina::HomGroupPresentation::HomGroupPresentation (const HomGroupPresentation &cloneMe)
| Creates a clone of the given group presentation. More...
| regina::HomGroupPresentation::~HomGroupPresentation ()
| Destroys the group homomorphism. More...
const GroupPresentation & | regina::HomGroupPresentation::domain () const
| The domain of the map. More...
const GroupPresentation & | regina::HomGroupPresentation::range () const
| The range of the map. More...
bool | regina::HomGroupPresentation::knowsInverse () const
| Returns whether or not this is a declared isomorphism. More...
GroupExpression | regina::HomGroupPresentation::evaluate (const GroupExpression &arg) const
| Evaluate the homomorphism at an element of the domain. More...
GroupExpression | regina::HomGroupPresentation::evaluate (unsigned long i) const
| Evaluate the homomorphism at a generator of the domain. More...
GroupExpression | regina::HomGroupPresentation::invEvaluate (const GroupExpression &arg) const
| Evaluate the isomorphisms's inverse at an element of the range. More...
GroupExpression | regina::HomGroupPresentation::invEvaluate (unsigned long i) const
| Evaluate the isomorphism at a generator of the range. More...
bool | regina::HomGroupPresentation::intelligentSimplify ()
| Simultaneously simplifies: More...
bool | regina::HomGroupPresentation::intelligentNielsen ()
| Simplifies the domain and range using only Nielsen moves, keeping track of the resulting map in the progress. More...
bool | regina::HomGroupPresentation::smallCancellation ()
| Simplifies the domain and range using only small cancellation theory. More...
std::unique_ptr< HomGroupPresentation > | regina::HomGroupPresentation::composeWith (const HomGroupPresentation &input) const
| Composes this homomorphism with the given input homomorphism. More...
bool | regina::HomGroupPresentation::invert ()
| Inverts the homomorphism. More...
bool | regina::HomGroupPresentation::verify () const
| Verifies the map is a valid homomorphism. More...
bool | regina::HomGroupPresentation::verifyIsomorphism () const
| Attempts to verify that a declared isomorphism is, indeed, an isomorphism. More...
std::unique_ptr< HomMarkedAbelianGroup > | regina::HomGroupPresentation::markedAbelianisation () const
| Computes the induced map on the abelianizations of the domain and range. More...
void | regina::HomGroupPresentation::writeTextShort (std::ostream &out) const
| Writes a short text representation of this object to the given output stream. More...
void | regina::HomGroupPresentation::writeTextLong (std::ostream &out) const
| Writes a detailed text representation of this object to the given output stream. More...
| regina::MarkedAbelianGroup::MarkedAbelianGroup (const MatrixInt &M, const MatrixInt &N)
| Creates a marked abelian group from a chain complex. More...
| regina::MarkedAbelianGroup::MarkedAbelianGroup (const MatrixInt &M, const MatrixInt &N, const Integer &pcoeff)
| Creates a marked abelian group from a chain complex with coefficients in Z_p. More...
| regina::MarkedAbelianGroup::MarkedAbelianGroup (unsigned long rk, const Integer &p)
| Creates a free Z_p-module of a given rank using the direct sum of the standard chain complex `0 --> Z –p--> Z --> 0`. More...
| regina::MarkedAbelianGroup::MarkedAbelianGroup (const MarkedAbelianGroup &cloneMe)
| Creates a clone of the given group. More...
bool | regina::MarkedAbelianGroup::isChainComplex () const
| Determines whether or not the defining maps for this group actually give a chain complex. More...
unsigned long | regina::MarkedAbelianGroup::rank () const
| Returns the rank of the group. More...
unsigned long | regina::MarkedAbelianGroup::torsionRank (const Integer &degree) const
| Returns the rank in the group of the torsion term of given degree. More...
unsigned long | regina::MarkedAbelianGroup::torsionRank (unsigned long degree) const
| Returns the rank in the group of the torsion term of given degree. More...
size_t | regina::MarkedAbelianGroup::countInvariantFactors () const
| Returns the number of invariant factors that describe the torsion elements of this group. More...
unsigned long | regina::MarkedAbelianGroup::minNumberOfGenerators () const
| Returns the minimum number of generators for the group. More...
const Integer & | regina::MarkedAbelianGroup::invariantFactor (size_t index) const
| Returns the given invariant factor describing the torsion elements of this group. More...
bool | regina::MarkedAbelianGroup::isTrivial () const
| Determines whether this is the trivial (zero) group. More...
REGINA_INLINE_REQUIRED bool | regina::MarkedAbelianGroup::isIsomorphicTo (const MarkedAbelianGroup &other) const
| Determines whether this and the given abelian group are isomorphic. More...
bool | regina::MarkedAbelianGroup::equalTo (const MarkedAbelianGroup &other) const
| Determines whether or not the two MarkedAbelianGroups are identical, which means they have exactly the same presentation matrices. More...
void | regina::MarkedAbelianGroup::writeTextShort (std::ostream &out, bool utf8=false) const
| The text representation will be of the form `3 Z + 4 Z_2 + Z_120`. More...
std::vector< Integer > | regina::MarkedAbelianGroup::freeRep (unsigned long index) const
| Returns the requested free generator in the original chain complex defining the group. More...
std::vector< Integer > | regina::MarkedAbelianGroup::torsionRep (unsigned long index) const
| Returns the requested generator of the torsion subgroup but represented in the original chain complex defining the group. More...
std::vector< Integer > | regina::MarkedAbelianGroup::ccRep (const std::vector< Integer > &SNFRep) const
| A combination of freeRep and torsionRep, this routine takes a vector which represents an element in the group in the SNF coordinates and returns a corresponding vector in the original chain complex. More...
std::vector< Integer > | regina::MarkedAbelianGroup::ccRep (unsigned long SNFRep) const
| Same as ccRep(const std::vector<Integer>&), but we assume you only want the chain complex representation of a standard basis vector from SNF coordinates. More...
std::vector< Integer > | regina::MarkedAbelianGroup::cycleProjection (const std::vector< Integer > &ccelt) const
| Projects an element of the chain complex to the subspace of cycles. More...
std::vector< Integer > | regina::MarkedAbelianGroup::cycleProjection (unsigned long ccindx) const
| Projects an element of the chain complex to the subspace of cycles. More...
bool | regina::MarkedAbelianGroup::isCycle (const std::vector< Integer > &input) const
| Given a vector, determines if it represents a cycle in the chain complex. More...
std::vector< Integer > | regina::MarkedAbelianGroup::boundaryMap (const std::vector< Integer > &CCrep) const
| Computes the differential of the given vector in the chain complex whose kernel is the cycles. More...
bool | regina::MarkedAbelianGroup::isBoundary (const std::vector< Integer > &input) const
| Given a vector, determines if it represents a boundary in the chain complex. More...
std::vector< Integer > | regina::MarkedAbelianGroup::writeAsBoundary (const std::vector< Integer > &input) const
| Expresses the given vector as a boundary in the chain complex (if the vector is indeed a boundary at all). More...
unsigned long | regina::MarkedAbelianGroup::rankCC () const
| Returns the rank of the chain complex supporting the homology computation. More...
std::vector< Integer > | regina::MarkedAbelianGroup::snfRep (const std::vector< Integer > &v) const
| Expresses the given vector as a combination of free and torsion generators. More...
unsigned long | regina::MarkedAbelianGroup::minNumberCycleGens () const
| Returns the number of generators of ker(M), where M is one of the defining matrices of the chain complex. More...
std::vector< Integer > | regina::MarkedAbelianGroup::cycleGen (unsigned long i) const
| Returns the ith generator of the cycles, i.e., the kernel of M in the chain complex. More...
const MatrixInt & | regina::MarkedAbelianGroup::M () const
| Returns the ‘right’ matrix used in defining the chain complex. More...
const MatrixInt & | regina::MarkedAbelianGroup::N () const
| Returns the ‘left’ matrix used in defining the chain complex. More...
const Integer & | regina::MarkedAbelianGroup::coefficients () const
| Returns the coefficients used for the computation of homology. More...
std::unique_ptr< MarkedAbelianGroup > | regina::MarkedAbelianGroup::torsionSubgroup () const
| Returns a MarkedAbelianGroup representing the torsion subgroup of this group. More...
std::unique_ptr< HomMarkedAbelianGroup > | regina::MarkedAbelianGroup::torsionInclusion () const
| Returns a HomMarkedAbelianGroup representing the inclusion of the torsion subgroup into this group. More...
| regina::HomMarkedAbelianGroup::HomMarkedAbelianGroup (const MarkedAbelianGroup &dom, const MarkedAbelianGroup &ran, const MatrixInt &mat)
| Constructs a homomorphism from two marked abelian groups and a matrix that indicates where the generators are sent. More...
| regina::HomMarkedAbelianGroup::HomMarkedAbelianGroup (const HomMarkedAbelianGroup &h)
| Copy constructor. More...
| regina::HomMarkedAbelianGroup::~HomMarkedAbelianGroup ()
| Destructor. More...
bool | regina::HomMarkedAbelianGroup::isChainMap (const HomMarkedAbelianGroup &other) const
| Determines whether this and the given homomorphism together form a chain map. More...
bool | regina::HomMarkedAbelianGroup::isCycleMap () const
| Is this at least a cycle map? If not, pretty much any further computations you try with this class will be give you nothing more than carefully-crafted garbage. More...
bool | regina::HomMarkedAbelianGroup::isEpic () const
| Is this an epic homomorphism? More...
bool | regina::HomMarkedAbelianGroup::isMonic () const
| Is this a monic homomorphism? More...
REGINA_INLINE_REQUIRED bool | regina::HomMarkedAbelianGroup::isIsomorphism () const
| Is this an isomorphism? More...
bool | regina::HomMarkedAbelianGroup::isZero () const
| Is this the zero map? More...
bool | regina::HomMarkedAbelianGroup::isIdentity () const
| Is this the identity automorphism? More...
const REGINA_INLINE_REQUIRED MarkedAbelianGroup & | regina::HomMarkedAbelianGroup::kernel () const
| Returns the kernel of this homomorphism. More...
const REGINA_INLINE_REQUIRED MarkedAbelianGroup & | regina::HomMarkedAbelianGroup::cokernel () const
| Returns the cokernel of this homomorphism. More...
const REGINA_INLINE_REQUIRED MarkedAbelianGroup & | regina::HomMarkedAbelianGroup::image () const
| Returns the image of this homomorphism. More...
void | regina::HomMarkedAbelianGroup::writeTextShort (std::ostream &out) const
| Short text representation. More...
void | regina::HomMarkedAbelianGroup::writeTextLong (std::ostream &out) const
| A more detailed text representation of the homomorphism. More...
const MarkedAbelianGroup & | regina::HomMarkedAbelianGroup::domain () const
| Returns the domain of this homomorphism. More...
const MarkedAbelianGroup & | regina::HomMarkedAbelianGroup::range () const
| Returns the range of this homomorphism. More...
const MatrixInt & | regina::HomMarkedAbelianGroup::definingMatrix () const
| Returns the defining matrix for the homomorphism. More...
const MatrixInt & | regina::HomMarkedAbelianGroup::reducedMatrix () const
| Returns the internal reduced matrix representing the homomorphism. More...
std::vector< Integer > | regina::HomMarkedAbelianGroup::evalCC (const std::vector< Integer > &input) const
| Evaluate the image of a vector under this homomorphism, using the original chain complexes' coordinates. More...
std::vector< Integer > | regina::HomMarkedAbelianGroup::evalSNF (const std::vector< Integer > &input) const
| Evaluate the image of a vector under this homomorphism, using the Smith normal form coordinates. More...
std::unique_ptr< HomMarkedAbelianGroup > | regina::HomMarkedAbelianGroup::inverseHom () const
| Returns the inverse to a HomMarkedAbelianGroup. More...
std::unique_ptr< HomMarkedAbelianGroup > | regina::HomMarkedAbelianGroup::operator* (const HomMarkedAbelianGroup &X) const
| Returns the composition of two homomorphisms. More...
std::unique_ptr< HomMarkedAbelianGroup > | regina::HomMarkedAbelianGroup::torsionSubgroup () const
| Returns a HomMarkedAbelianGroup representing the induced map on the torsion subgroups. More...
void | regina::HomMarkedAbelianGroup::writeReducedMatrix (std::ostream &out) const
| Writes a human-readable version of the reduced matrix to the given output stream. More...
| regina::XMLAbelianGroupReader::XMLAbelianGroupReader ()
| Creates a new abelian group reader. More...
virtual AbelianGroup * | regina::XMLAbelianGroupReader::group ()
| Returns the newly allocated abelian group that has been read by this element reader. More...
virtual void | regina::XMLAbelianGroupReader::startElement (const std::string &tagName, const regina::xml::XMLPropertyDict &tagProps, XMLElementReader *parentReader)
| Signifies that parsing of this XML element is beginning. More...
virtual void | regina::XMLAbelianGroupReader::initialChars (const std::string &chars)
| Signifies that the initial text belonging to this XML element has been read. More...
| regina::XMLGroupPresentationReader::XMLGroupPresentationReader ()
| Creates a new group presentation reader. More...
virtual GroupPresentation * | regina::XMLGroupPresentationReader::group ()
| Returns the newly allocated group presentation that has been read by this element reader. More...
virtual void | regina::XMLGroupPresentationReader::startElement (const std::string &tagName, const regina::xml::XMLPropertyDict &tagProps, XMLElementReader *parentReader)
| Signifies that parsing of this XML element is beginning. More...
virtual XMLElementReader * | regina::XMLGroupPresentationReader::startSubElement (const std::string &subTagName, const regina::xml::XMLPropertyDict &subTagProps)
| Signifies that a subelement of this XML element is about to be parsed. More...
virtual void | regina::XMLGroupPresentationReader::endSubElement (const std::string &subTagName, XMLElementReader *subReader)
| Signifies that parsing has finished for a subelement of this XML element. More...

## Variables

unsigned | regina::AbelianGroup::rank_
| The rank of the group (the number of Z components). More...
std::multiset< Integer > | regina::AbelianGroup::invariantFactors
| The invariant factors d0,...,dn as described in the AbelianGroup notes. More...
unsigned long | regina::GroupExpressionTerm::generator
| The number that identifies the generator in this term. More...
long | regina::GroupExpressionTerm::exponent
| The exponent to which the generator is raised. More...
unsigned long | regina::GroupPresentation::nGenerators
| The number of generators. More...
std::vector< GroupExpression * > | regina::GroupPresentation::relations
| The relations between the generators. More...
unsigned long | regina::GroupPresentation::NWordSubstitutionData::start_sub_at
| Where in A do we start? More...
unsigned long | regina::GroupPresentation::NWordSubstitutionData::start_from
| Where in B do we start? More...
unsigned long | regina::GroupPresentation::NWordSubstitutionData::sub_length
| The number of letters from B to use. More...
bool | regina::GroupPresentation::NWordSubstitutionData::invertB
| Invert B before making the substitution? More...
long int | regina::GroupPresentation::NWordSubstitutionData::score
| The score, i.e., the decrease in the word letter count provided this substitution is made. More...

## Friends

class | regina::MarkedAbelianGroup::HomMarkedAbelianGroup

## Detailed Description

Various algebraic structures.

## Typedef Documentation

## NAbelianGroup

typedef AbelianGroup regina::NAbelianGroup

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NAbelianGroup has now been renamed to AbelianGroup.

## NGroupExpression

typedef GroupExpression regina::NGroupExpression

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The struct NGroupExpression has now been renamed to GroupExpression.

## NGroupExpressionTerm

typedef GroupExpressionTerm regina::NGroupExpressionTerm

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The struct NGroupExpressionTerm has now been renamed to GroupExpressionTerm.

## NGroupPresentation

typedef GroupPresentation regina::NGroupPresentation

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The struct NGroupPresentation has now been renamed to GroupPresentation.

## NHomGroupPresentation

typedef HomGroupPresentation regina::NHomGroupPresentation

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NHomGroupPresentation has now been renamed to HomGroupPresentation.

## NHomMarkedAbelianGroup

typedef HomMarkedAbelianGroup regina::NHomMarkedAbelianGroup

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NHomMarkedAbelianGroup has now been renamed to HomMarkedAbelianGroup.

## NMarkedAbelianGroup

typedef MarkedAbelianGroup regina::NMarkedAbelianGroup

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NMarkedAbelianGroup has now been renamed to MarkedAbelianGroup.

## Function Documentation

## AbelianGroup() [1/4]

regina::AbelianGroup::AbelianGroup | ( |  | ) |

inline

Creates a new trivial group.

## AbelianGroup() [2/4]

regina::AbelianGroup::AbelianGroup | ( | const AbelianGroup & | cloneMe | ) |

inline

Creates a clone of the given group.

Parameters

  cloneMe | the group to clone.

## AbelianGroup() [3/4]

regina::AbelianGroup::AbelianGroup | ( | const MatrixInt & | M,
|  | const MatrixInt & | N
| ) |  |

Creates an abelian group as the homology of a chain complex.

Precondition
  M.columns() = N.rows().
  The product M*N = 0.

Parameters

  M | the ‘right’ matrix in the chain complex; that is, the matrix that one takes the kernel of when computing homology.
  N | the ‘left’ matrix in the chain complex; that is, the matrix that one takes the image of when computing homology.

Author
  Ryan Budney

## AbelianGroup() [4/4]

regina::AbelianGroup::AbelianGroup | ( | const MatrixInt & | M,
|  | const MatrixInt & | N,
|  | const Integer & | p
| ) |  |

Creates an abelian group as the homology of a chain complex, using mod-p coefficients.

Precondition
  M.columns() = N.rows().
  The product M*N = 0.

Parameters

  M | the ‘right’ matrix in the chain complex; that is, the matrix that one takes the kernel of when computing homology.
  N | the ‘left’ matrix in the chain complex; that is, the matrix that one takes the image of when computing homology.
  p | the modulus, which may be any Integer. Zero is interpreted as a request for integer coefficents, which will give the same result as the AbelianGroup(const MatrixInt&, const MatrixInt&) constructor.

Author
  Ryan Budney

## abelianisation()

std::unique_ptr<AbelianGroup> regina::GroupPresentation::abelianisation | ( |  | ) | const

Computes the abelianisation of this group.

Returns
  a newly allocated abelianisation of this group.

## addGenerator()

unsigned long regina::GroupPresentation::addGenerator | ( | unsigned long | numToAdd = `1` | ) |

inline

Adds one or more generators to the group presentation.

If the new presentation has g generators, the new generators will be numbered g-1, g-2 and so on.

Parameters

  numToAdd | the number of generators to add.

Returns
  the number of generators in the new presentation.

## addGroup() [1/2]

void regina::AbelianGroup::addGroup | ( | const AbelianGroup & | group | ) |

Adds the given abelian group to this group.

Note that this routine might be slow since calculating the new invariant factors is not trivial.

Parameters

  group | the group to add to this one.

## addGroup() [2/2]

void regina::AbelianGroup::addGroup | ( | const MatrixInt & | presentation | ) |

Adds the abelian group defined by the given presentation to this group.

Note that this routine might be slow since calculating the new invariant factors is not trivial.

Parameters

  presentation | a presentation matrix for the group to be added to this group, where each column represents a generator and each row a relation.

## addRank()

void regina::AbelianGroup::addRank | ( | int | extraRank = `1` | ) |

inline

Increments the rank of the group by the given integer.

This integer may be positive, negative or zero.

Precondition
  The current rank plus the given integer is non-negative. In other words, if we are subtracting rank then we are not trying to subtract more rank than the group actually has.

Parameters

  extraRank | the extra rank to add; this defaults to 1.

## addRelation()

void regina::GroupPresentation::addRelation | ( | GroupExpression * | rel | ) |

inline

Adds the given relation to the group presentation.

The relation must be of the form `expression = 1`.

This presentation will take ownership of the given expression, may change it and will be responsible for its deallocation.

Warning
  This routine does not check whether or not your relation is a word only in the generators of this group. In other words, it does not stop you from using generators beyond the countGenerators() bound.

Python:\n In Python, this routine clones its argument
  instead of claiming ownership of it.

Parameters

  rel | the expression that the relation sets to 1; for instance, if the relation is `g1^2 g2 = 1` then this parameter should be the expression `g1^2 g2`.

## addStringFirst()

bool regina::GroupExpression::addStringFirst | ( | const std::string & | input | ) |

Multiplies this expression on the left by the word respresented by the given string.

See the string-based constructor GroupExpression(const std::string&, bool*) for further information on how this string should be formatted.

If the given string cannot be interpreted as a word in a group, then this expression will be left untouched.

Parameters

  input | a string representation of the word to multiply with this expression.

Returns
  `true` if the given string could interpreted (and therefore the multiplication was completed successfully), or `false` if the given string could not be interpreted (in which case this expression will be left untouched).

## addStringLast()

bool regina::GroupExpression::addStringLast | ( | const std::string & | input | ) |

Multiplies this expression on the right by the word respresented by the given string.

See the string-based constructor GroupExpression(const std::string&, bool*) for further information on how this string should be formatted.

If the given string cannot be interpreted as a word in a group, then this expression will be left untouched.

Parameters

  input | a string representation of the word to multiply with this expression.

Returns
  `true` if the given string could interpreted (and therefore the multiplication was completed successfully), or `false` if the given string could not be interpreted (in which case this expression will be left untouched).

## addTermFirst() [1/2]

void regina::GroupExpression::addTermFirst | ( | const GroupExpressionTerm & | term | ) |

inline

Adds the given term to the beginning of this expression.

Parameters

  term | the term to add.

## addTermFirst() [2/2]

void regina::GroupExpression::addTermFirst | ( | unsigned long | generator,
|  | long | exponent
| ) |  |

inline

Adds the given term to the beginning of this expression.

Parameters

  generator | the number of the generator corresponding to the new term.
  exponent | the exponent to which the given generator is raised.

## addTermLast() [1/2]

void regina::GroupExpression::addTermLast | ( | const GroupExpressionTerm & | term | ) |

inline

Adds the given term to the end of this expression.

Parameters

  term | the term to add.

## addTermLast() [2/2]

void regina::GroupExpression::addTermLast | ( | unsigned long | generator,
|  | long | exponent
| ) |  |

inline

Adds the given term to the end of this expression.

Parameters

  generator | the number of the generator corresponding to the new term.
  exponent | the exponent to which the given generator is raised.

## addTermsFirst()

void regina::GroupExpression::addTermsFirst | ( | const GroupExpression & | word | ) |

Multiplies this expression on the left by the given word.

This expression will be modified directly.

Parameters

  word | the word to multiply with this expression.

## addTermsLast()

void regina::GroupExpression::addTermsLast | ( | const GroupExpression & | word | ) |

Multiplies this expression on the right by the given word.

This expression will be modified directly.

Parameters

  word | the word to multiply with this expression.

## addTorsionElement() [1/2]

void regina::AbelianGroup::addTorsionElement | ( | const Integer & | degree,
|  | unsigned | mult = `1`
| ) |  |

Adds the given torsion element to the group.

Note that this routine might be slow since calculating the new invariant factors is not trivial. If many different torsion elements are to be added, consider using addTorsionElements() instead so the invariant factors need only be calculated once.

In this routine we add a specified number of copies of Z_d, where d is some given degree.

Precondition
  The given degree is at least 2 and the given multiplicity is at least 1.

Parameters

  degree | d, where we are adding copies of Z_d to the torsion.
  mult | the multiplicity m, where we are adding precisely m copies of Z_d; this defaults to 1.

## addTorsionElement() [2/2]

void regina::AbelianGroup::addTorsionElement | ( | unsigned long | degree,
|  | unsigned | mult = `1`
| ) |  |

inline

Adds the given torsion element to the group.

Note that this routine might be slow since calculating the new invariant factors is not trivial. If many different torsion elements are to be added, consider using addTorsionElements() instead so the invariant factors need only be calculated once.

In this routine we add a specified number of copies of Z_d, where d is some given degree.

Precondition
  The given degree is at least 2 and the given multiplicity is at least 1.

Parameters

  degree | d, where we are adding copies of Z_d to the torsion.
  mult | the multiplicity m, where we are adding precisely m copies of Z_d; this defaults to 1.

## addTorsionElements()

void regina::AbelianGroup::addTorsionElements | ( | const std::multiset< Integer > & | torsion | ) |

Adds the given set of torsion elements to this group.

Note that this routine might be slow since calculating the new invariant factors is not trivial.

The torsion elements to add are described by a list of integers k1,...,km, where we are adding Z_k1,...,Z_km. Unlike invariant factors, the ki are not required to divide each other.

Precondition
  Each integer in the given list is strictly greater than 1.

Python:\n This routine takes a python list as its argument.

Parameters

  torsion | a list containing the torsion elements to add, as described above.

## boundaryMap()

std::vector<Integer> regina::MarkedAbelianGroup::boundaryMap | ( | const std::vector< Integer > & | CCrep | ) | const

Computes the differential of the given vector in the chain complex whose kernel is the cycles.

In other words, this routine returns `M*CCrep`.

Python:\n Not available yet. This routine will be made
  accessible to Python in a future release.

Parameters

  CCrep | a vector whose length is M.columns(), where M is one of the matrices that defines the chain complex (see the class notes for details).

Returns
  the differential, expressed as a vector of length M.rows().

## ccRep() [1/2]

std::vector<Integer> regina::MarkedAbelianGroup::ccRep | ( | const std::vector< Integer > & | SNFRep | ) | const

A combination of freeRep and torsionRep, this routine takes a vector which represents an element in the group in the SNF coordinates and returns a corresponding vector in the original chain complex.

This routine is the inverse to snfRep() described below.

Warning
  The return value may change from version to version of Regina, since it depends on the choice of Smith normal form.

Python:\n Not available yet. This routine will be made
  accessible to Python in a future release.

Parameters

  SNFRep | a vector of size the number of generators of the group, i.e., it must be valid in the SNF coordinates. If not, an empty vector is returned.

Returns
  a corresponding vector whose length is M.columns(), where M is one of the matrices that defines the chain complex; see the class notes for details.

## ccRep() [2/2]

std::vector<Integer> regina::MarkedAbelianGroup::ccRep | ( | unsigned long | SNFRep | ) | const

Same as ccRep(const std::vector<Integer>&), but we assume you only want the chain complex representation of a standard basis vector from SNF coordinates.

Warning
  The return value may change from version to version of Regina, since it depends on the choice of Smith normal form.

Python:\n Not available yet. This routine will be made
  accessible to Python in a future release.

Parameters

  SNFRep | specifies which standard basis vector from SNF coordinates; this must be between 0 and minNumberOfGenerators()-1 inclusive.

Returns
  a corresponding vector whose length is M.columns(), where M is one of the matrices that defines the chain complex; see the class notes for details.

## coefficients()

const Integer & regina::MarkedAbelianGroup::coefficients | ( |  | ) | const

inline

Returns the coefficients used for the computation of homology.

That is, this routine returns the integer p where we use coefficients in Z_p. If we use coefficients in the integers Z, then this routine returns 0.

Returns
  the coefficients used in the homology calculation.

## cokernel()

const MarkedAbelianGroup & regina::HomMarkedAbelianGroup::cokernel | ( |  | ) | const

inline

Returns the cokernel of this homomorphism.

Returns
  the cokernel of the homomorphism, as a marked abelian group.

## compact()

std::string regina::GroupPresentation::compact | ( |  | ) | const

Returns a compact one-line representation of this group presentation, including details of all generators and relations.

See writeTextCompact() for details on how this is formed.

Returns
  a compact representation of this group presentation.

## composeWith()

std::unique_ptr<HomGroupPresentation> regina::HomGroupPresentation::composeWith | ( | const HomGroupPresentation & | 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.

## countGenerators()

unsigned long regina::GroupPresentation::countGenerators | ( |  | ) | const

inline

Returns the number of generators in this group presentation.

Returns
  the number of generators.

## countInvariantFactors() [1/2]

size_t regina::AbelianGroup::countInvariantFactors | ( |  | ) | const

inline

Returns the number of invariant factors that describe the torsion elements of this group.

See the AbelianGroup class notes for further details.

Returns
  the number of invariant factors.

## countInvariantFactors() [2/2]

size_t regina::MarkedAbelianGroup::countInvariantFactors | ( |  | ) | const

inline

Returns the number of invariant factors that describe the torsion elements of this group.

This is the minimal number of torsion generators. See the MarkedAbelianGroup class notes for further details.

Returns
  the number of invariant factors.

## countRelations()

size_t regina::GroupPresentation::countRelations | ( |  | ) | const

inline

Returns the number of relations in this group presentation.

Returns
  the number of relations.

## countTerms()

size_t regina::GroupExpression::countTerms | ( |  | ) | const

inline

Returns the number of terms in this expression.

For instance, the expression `g1^2 g3^-1 g6` contains three terms. See also wordLength().

Returns
  the number of terms.

## cycleGen()

std::vector<Integer> regina::MarkedAbelianGroup::cycleGen | ( | unsigned long | i | ) | const

Returns the ith generator of the cycles, i.e., the kernel of M in the chain complex.

Warning
  The return value may change from version to version of Regina, as it depends on the choice of Smith normal form.

Python:\n Not available yet. This routine will be made
  accessible to Python in a future release.

Parameters

  i | between 0 and minNumCycleGens()-1.

Returns
  the corresponding generator in chain complex coordinates.

## cycleLeft()

void regina::GroupExpression::cycleLeft | ( |  | ) |

Cycles this word by moving the rightmost term around to the leftmost.

All other terms shift one step to the right.

If the word is of the form `g_i1^j1 g_i2^j2 ... g_in^jn`, this converts it into the word `g_in^jn g_i1^j1 g_i1^j1 ... g_in-1^jn-1`.

## cycleProjection() [1/2]

std::vector<Integer> regina::MarkedAbelianGroup::cycleProjection | ( | const std::vector< Integer > & | ccelt | ) | const

Projects an element of the chain complex to the subspace of cycles.

Returns an empty vector if the input element does not have dimensions of the chain complex.

Warning
  The return value may change from version to version of Regina, since it depends on the choice of Smith normal form.

Python:\n Not available yet. This routine will be made
  accessible to Python in a future release.

Parameters

  ccelt | a vector whose length is M.columns(), where M is one of the matrices that defines the chain complex (see the class notes for details).

Returns
  a corresponding vector, also in the chain complex coordinates.

## cycleProjection() [2/2]

std::vector<Integer> regina::MarkedAbelianGroup::cycleProjection | ( | unsigned long | ccindx | ) | const

Projects an element of the chain complex to the subspace of cycles.

Returns an empty vector if the input index is out of bounds.

Warning
  The return value may change from version to version of Regina, since it depends on the choice of Smith normal form.

Python:\n Not available yet. This routine will be made
  accessible to Python in a future release.

Parameters

  ccindx | the index of the standard basis vector in chain complex coordinates.

Returns
  the resulting projection, in the chain complex coordinates.

## cycleRight()

void regina::GroupExpression::cycleRight | ( |  | ) |

Cycles this word by moving the leftmost term around to the rightmost.

All other terms shift one step to the left.

If the word is of the form `g_i1^j1 g_i2^j2 ... g_in^jn`, this converts it into the word `g_i2^j2 ... g_in^jn g_i1^j1`.

## definingMatrix()

const MatrixInt & regina::HomMarkedAbelianGroup::definingMatrix | ( |  | ) | const

inline

Returns the defining matrix for the homomorphism.

Returns
  the matrix that was used to define the homomorphism.

## domain() [1/2]

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

inline

The domain of the map.

Returns
  a reference to the domain.

## domain() [2/2]

const MarkedAbelianGroup & regina::HomMarkedAbelianGroup::domain | ( |  | ) | const

inline

Returns the domain of this homomorphism.

Returns
  the domain that was used to define the homomorphism.

## endSubElement()

virtual void regina::XMLGroupPresentationReader::endSubElement | ( | const std::string & | subTagName,
|  | XMLElementReader * | subReader
| ) |  |

virtual

Signifies that parsing has finished for a subelement of this XML element.

The default implementation does nothing.

Parameters

  subTagName | the name of the subelement closing tag.
  subReader | the child reader that was used to parse the subelement (this is the reader that was returned by the corresponding startSubElement() call). It is guaranteed that endElement() has already been called upon this child reader and that the child reader has not yet been destroyed.

Reimplemented from regina::XMLElementReader.

## equalTo()

bool regina::MarkedAbelianGroup::equalTo | ( | const MarkedAbelianGroup & | other | ) | const

inline

Determines whether or not the two MarkedAbelianGroups are identical, which means they have exactly the same presentation matrices.

This is useful for determining if two HomMarkedAbelianGroups are composable. See isIsomorphicTo() if all you care about is the isomorphism relation among groups defined by presentation matrices.

Parameters

  other | the MarkedAbelianGroup with which this should be compared.

Returns
  `true` if and only if the two groups have identical chain-complex definitions.

## erase()

void regina::GroupExpression::erase | ( |  | ) |

inline

Erases all terms from this this word.

This effectively turns this word into the identity element.

## evalCC()

std::vector<Integer> regina::HomMarkedAbelianGroup::evalCC | ( | const std::vector< Integer > & | input | ) | const

Evaluate the image of a vector under this homomorphism, using the original chain complexes' coordinates.

This involves multiplication by the defining matrix.

Python:\n Not available yet. This routine will be made
  accessible to Python in a future release.

Parameters

  input | an input vector in the domain chain complex's coordinates, of length domain().M().columns().

Returns
  the image of this vector in the range chain complex's coordinates, of length range().M().columns().

## evalSNF()

std::vector<Integer> regina::HomMarkedAbelianGroup::evalSNF | ( | const std::vector< Integer > & | input | ) | const

Evaluate the image of a vector under this homomorphism, using the Smith normal form coordinates.

This is just multiplication by the reduced matrix, returning the empty vector if the input vector has the wrong dimensions.

Warning
  Smith normal form coordinates are sensitive to the implementation of the Smith Normal Form, i.e., they are not canonical.

Python:\n Not available yet. This routine will be made
  accessible to Python in a future release.

Parameters

  input | an input vector in the domain SNF coordinates, of length domain().minNumberOfGenerators().

Returns
  the image of this vector in the range chain complex's coordinates, of length range().minNumberOfGenerators().

## evaluate() [1/2]

GroupExpression regina::HomGroupPresentation::evaluate | ( | const GroupExpression & | 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.

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

## exponent()

long regina::GroupExpression::exponent | ( | size_t | index | ) | const

inline

Returns the exponent corresonding to the term at the given index in this expression.

Index 0 represents the first term, index 1 represents the second term and so on.

Warning
  This routine is O(n) where n is the number of terms in this expression.

Parameters

  index | the index of the term to return; this must be between 0 and countTerms()-1 inclusive.

Returns
  the requested exponent.

## freeRep()

std::vector<Integer> regina::MarkedAbelianGroup::freeRep | ( | unsigned long | index | ) | const

Returns the requested free generator in the original chain complex defining the group.

As described in the class overview, this marked abelian group is defined by matrices M and N where M*N = 0. If M is an m by l matrix and N is an l by n matrix, then this routine returns the (index)th free generator of ker(M)/img(N) in Z^l.

Warning
  The return value may change from version to version of Regina, since it depends on the choice of Smith normal form.

Python:\n The return value will be a python list.

Parameters

  index | specifies which free generator to look up; this must be between 0 and rank()-1 inclusive.

Returns
  the coordinates of the free generator in the nullspace of M; this vector will have length M.columns() (or equivalently, N.rows()). If this generator does not exist, you will receive an empty vector.

## generator()

unsigned long regina::GroupExpression::generator | ( | size_t | index | ) | const

inline

Returns the generator corresonding to the term at the given index in this expression.

Index 0 represents the first term, index 1 represents the second term and so on.

Warning
  This routine is O(n) where n is the number of terms in this expression.

Parameters

  index | the index of the term to return; this must be between 0 and countTerms()-1 inclusive.

Returns
  the number of the requested generator.

## group() [1/2]

AbelianGroup * regina::XMLAbelianGroupReader::group | ( |  | ) |

inline virtual

Returns the newly allocated abelian group that has been read by this element reader.

Returns
  the group that has been read, or 0 if an error occurred.

## group() [2/2]

GroupPresentation * regina::XMLGroupPresentationReader::group | ( |  | ) |

inline virtual

Returns the newly allocated group presentation that has been read by this element reader.

Returns
  the group that has been read, or 0 if an error occurred.

## GroupExpression() [1/3]

regina::GroupExpression::GroupExpression | ( |  | ) |

inline

The terms that make up this expression.

Creates a new expression with no terms.

## GroupExpression() [2/3]

regina::GroupExpression::GroupExpression | ( | const GroupExpression & | cloneMe | ) |

inline

Creates a new expression that is a clone of the given expression.

Parameters

  cloneMe | the expression to clone.

## GroupExpression() [3/3]

regina::GroupExpression::GroupExpression | ( | const std::string & | input,
|  | bool * | valid = `NULL`
| ) |  |

Attempts to interpret the given input string as a word in a group.

Regina can recognise strings in the following four basic forms:

- `a^7b^-2`
- `aaaaaaaBB`
- `a^7B^2`
- `g0^7g1^-2`

The string may contain whitespace, which will simply be ignored.

The argument valid may be `null`, but if it is non-null then the boolean it points to will be used for error reporting. This routine sets valid to `true` if the string was successfully interpreted, or `false` if the algorithm failed to interpret the string.

Regardless of whether valid is `null`, if the string could not be interpreted then this expression will be initialised to the trivial word.

Python:\n The second argument valid is not present,
  and will be assumed to be `null`.

Parameters

  input | the input string that is to be interpreted.
  valid | used for error reporting as described above, or `null` if no error reporting is required.

## GroupExpressionTerm() [1/3]

regina::GroupExpressionTerm::GroupExpressionTerm | ( |  | ) |

inline

Creates a new uninitialised term.

## GroupExpressionTerm() [2/3]

regina::GroupExpressionTerm::GroupExpressionTerm | ( | const GroupExpressionTerm & | cloneMe | ) |

inline

Creates a new term initialised to the given value.

Parameters

  cloneMe | a term whose data will be copied to the new term.

## GroupExpressionTerm() [3/3]

regina::GroupExpressionTerm::GroupExpressionTerm | ( | unsigned long | newGen,
|  | long | newExp
| ) |  |

inline

Creates a new term initialised to the given value.

Parameters

  newGen | the number that identifies the generator in the new term.
  newExp | the exponent to which this generator is raised.

## GroupPresentation() [1/3]

regina::GroupPresentation::GroupPresentation | ( |  | ) |

inline

Creates a new presentation with no generators and no relations.

## GroupPresentation() [2/3]

regina::GroupPresentation::GroupPresentation | ( | const GroupPresentation & | cloneMe | ) |

Creates a clone of the given group presentation.

Parameters

  cloneMe | the presentation to clone.

## GroupPresentation() [3/3]

regina::GroupPresentation::GroupPresentation | ( | unsigned long | nGens,
|  | const std::vector< std::string > & | rels
| ) |  |

Constructor that allows you to directly pass an arbitrary number of relators in string format.

The first argument nGens is the number of generators one wants the group to have. The second argument rels is a vector of strings, where each string gives a single relator. See the GroupExpression::GroupExpression(const std::string&, bool*) constructor notes for information on what format these strings can take.

If any of the given strings could not be interpreted as words, this routine will insert the trivial (unit) word in its place.

If you are compiling Regina against C++11, you can use the C++11 initializer_list construction to construct an GroupPresentation directly using syntax of the form `GroupPresentation(nGens, { "rel1", "rel2", ... })`.

Python:\n Not present.

Parameters

  nGens | the number of generators.
  rels | a vector of relations each given in string form, as outlined above.

## HomGroupPresentation() [1/4]

regina::HomGroupPresentation::HomGroupPresentation | ( | const GroupPresentation & | domain,
|  | const GroupPresentation & | range,
|  | const std::vector< GroupExpression > & | map
| ) |  |

inline

Creates a new homomorphism from the given data.

Python:\n 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:\n Not present.

## HomGroupPresentation() [2/4]

regina::HomGroupPresentation::HomGroupPresentation | ( | const GroupPresentation & | domain,
|  | const GroupPresentation & | range,
|  | const std::vector< GroupExpression > & | map,
|  | const std::vector< GroupExpression > & | 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:\n 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.

## HomGroupPresentation() [3/4]

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

## HomGroupPresentation() [4/4]

regina::HomGroupPresentation::HomGroupPresentation | ( | const HomGroupPresentation & | cloneMe | ) |

inline

Creates a clone of the given group presentation.

Parameters

  cloneMe | the presentation to clone.

## HomMarkedAbelianGroup() [1/2]

regina::HomMarkedAbelianGroup::HomMarkedAbelianGroup | ( | const HomMarkedAbelianGroup & | h | ) |

Copy constructor.

Parameters

  h | the homomorphism to clone.

## HomMarkedAbelianGroup() [2/2]

regina::HomMarkedAbelianGroup::HomMarkedAbelianGroup | ( | const MarkedAbelianGroup & | dom,
|  | const MarkedAbelianGroup & | ran,
|  | const MatrixInt & | mat
| ) |  |

inline

Constructs a homomorphism from two marked abelian groups and a matrix that indicates where the generators are sent.

The roles of the two groups and the matrix are described in detail in the HomMarkedAbelianGroup class overview.

The matrix must be given in the chain-complex coordinates. Specifically, if the domain was defined via the chain complex `Z^a –N1--> Z^b –M1--> Z^c` and the range was defined via `Z^d –N2--> Z^e –M2--> Z^f`, then mat is an e-by-b matrix that describes a homomorphism from Z^b to Z^e.

In order for this to make sense as a homomorphism of the groups represented by the domain and range respectively, one requires img(mat*N1) to be a subset of img(N2). Similarly, ker(M1) must be sent into ker(M2). These facts are not checked, but are assumed as preconditions of this constructor.

Precondition
  The matrix mat has the required dimensions e-by-b, gives img(mat*N1) as a subset of img(N2), and sends ker(M1) into ker(M2), as explained in the detailed notes above.

Parameters

  dom | the domain group.
  ran | the range group.
  mat | the matrix that describes the homomorphism from dom to ran.

## homologicalAlignment()

bool regina::GroupPresentation::homologicalAlignment | ( |  | ) |

Rewrites the presentation so that generators of the group map to generators of the abelianisation, with any left-over generators mapping to zero (if possible).

Consider this a homological-alignment of the presentation.

See homologicalAlignmentDetail() for further details on what this routine does.

Returns
  `true` if presentation was changed, or `false` if the presentation was already homologically aligned. See homologicalAlignmentDetail() if you wish to get the isomorphism.

## homologicalAlignmentDetail()

std::unique_ptr<HomGroupPresentation> regina::GroupPresentation::homologicalAlignmentDetail | ( |  | ) |

Rewrites the presentation so that generators of the group map to generators of the abelianisation, with any left-over generators mapping to zero (if possible).

Consider this a homological-alignment of the presentation.

If the abelianisation of this group has rank N and M invariant factors `d0 | d2 | ... | d(M-1)`, this routine applies Nielsen moves to the presentation to ensure that under the markedAbelianisation() routine, generators 0 through M-1 are mapped to generators of the relevant `Z_di` group. Similarly, generators M through M+N-1 are mapped to +/-1 in the appropriate factor. All further generators will be mapped to zero.

If this routine does return a homomorphism (because the presentation was changed), then this homomorphsm will in fact be a declared isomorphism. See the HomGroupPresentation class notes for details on what this means.

Returns
  a newly allocated homomorphism giving the reduction map from the old presentation to the new, or a null pointer if this presentation was not changed.

## identifyAbelian()

bool regina::GroupPresentation::identifyAbelian | ( |  | ) | const

Attempts to determine if the group is abelian.

A return value of `true` indicates that this routine successfully certified that the group is abelian. A return value of `false` indicates an inconclusive result: either the group is non-abelian, or the group is abelian but this routine could not prove so.

If the group is abelian, then markedAbelianization() is the easiest way to see precisely which abelian group it is, and how the generators sit in that group.

You will have better results from this algorithm if the presentation has been simplified, since this algorithm uses small cancellation theory in an attempt to reduce the commutators of all pairs of generators.

Warning
  If you have not adequately simplified this presentation this routine will most likely return `false`. Consider running intelligentSimplify, possibly in concert with proliferateRelators(), in order to discover adequately many commutators.

Returns
  `true` if the group is shown to be abelian, or `false` if the result is inconclusive.

## identifySimplyIsomorphicTo()

bool regina::GroupPresentation::identifySimplyIsomorphicTo | ( | const GroupPresentation & | other | ) | const

Attempts to prove that this and the given group presentation are simply isomorphic.

A simple isomorphism is an isomorphism where each generator gi of this presentation is sent to some generator gj+/-1 of the other presentation. Moreover, at present this routine only looks for maps where both presentations have the same number of generators, and where distinct generators gi of this presentation correspond to distinct generators gj of the other presentation (possibly with inversion, as noted above).

If this routine returns `true`, it means that the two presentations are indeed simply isomorphic.

If this routine returns `false`, it could mean one of many things:

- The groups are not isomorphic;
- The groups are isomorphic, but not simply isomorphic;
- The groups are simply isomorphic but this routine could not prove it, due to difficulties with the word problem.

Parameters

  other | the group presentation to compare with this.

Returns
  `true` if this routine could certify that the two group presentations are simply isomorphic, or `false` if it could not.

## image()

const MarkedAbelianGroup & regina::HomMarkedAbelianGroup::image | ( |  | ) | const

inline

Returns the image of this homomorphism.

Returns
  the image of the homomorphism, as a marked abelian group.

## initialChars()

virtual void regina::XMLAbelianGroupReader::initialChars | ( | const std::string & | chars | ) |

virtual

Signifies that the initial text belonging to this XML element has been read.

The initial text is everything between the opening tag and the first subelement or closing tag.

The default implementation does nothing.

Parameters

  chars | the initial text for this element.

Reimplemented from regina::XMLElementReader.

## intelligentNielsen() [1/2]

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

## intelligentNielsen() [2/2]

bool regina::GroupPresentation::intelligentNielsen | ( |  | ) |

Looks for Nielsen moves that will simplify the presentation.

Performs one of the most-effective moves, if it can find any.

Returns
  `true` if and only if it performed a Nielsen move. You can call intelligentNielsen() to get the isomorphism.

## intelligentNielsenDetail()

std::unique_ptr<HomGroupPresentation> regina::GroupPresentation::intelligentNielsenDetail | ( |  | ) |

Looks for Nielsen moves that will simplify the presentation.

Performs one of the most-effective moves, if it can find any.

If this routine does return a homomorphism (because some move was performed), then this homomorphsm will in fact be a declared isomorphism. See the HomGroupPresentation class notes for details on what this means.

Returns
  a newly allocated homomorphism describing the map from the original presentation to the new presentation, or a null pointer if no move was performed.

## intelligentSimplify() [1/2]

bool regina::HomGroupPresentation::intelligentSimplify | ( |  | ) |

Simultaneously simplifies:

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

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

Returns
  `true` if the presentations or map have changed.

## intelligentSimplify() [2/2]

bool regina::GroupPresentation::intelligentSimplify | ( |  | ) |

Attempts to simplify the group presentation as intelligently as possible without further input.

See intelligentSimplifyDetail() for further details on how the simplification is done.

Returns
  `true` if and only if the group presentation was changed. You can call intelligentSimplifyDetail() to get the isomorphism.

## intelligentSimplifyDetail()

std::unique_ptr<HomGroupPresentation> regina::GroupPresentation::intelligentSimplifyDetail | ( |  | ) |

Attempts to simplify the group presentation as intelligently as possible without further input.

The current simplification method uses a combination of small cancellation theory and Nielsen moves.

If this routine does return a homomorphism (because the presentation was changed), then this homomorphsm will in fact be a declared isomorphism. See the HomGroupPresentation class notes for details on what this means.

Returns
  a newly allocated homomorphism describing the reduction map from the original presentation to the new presentation, or a null pointer if this presentation was not changed.

## invariantFactor() [1/2]

const Integer& regina::AbelianGroup::invariantFactor | ( | size_t | index | ) | const

Returns the given invariant factor describing the torsion elements of this group.

See the AbelianGroup class notes for further details.

If the invariant factors are d0|d1|...|dn, this routine will return di where i is the value of parameter index.

Parameters

  index | the index of the invariant factor to return; this must be between 0 and countInvariantFactors()-1 inclusive.

Returns
  the requested invariant factor.

## invariantFactor() [2/2]

const Integer & regina::MarkedAbelianGroup::invariantFactor | ( | size_t | index | ) | const

inline

Returns the given invariant factor describing the torsion elements of this group.

See the MarkedAbelianGroup class notes for further details.

If the invariant factors are d0|d1|...|dn, this routine will return di where i is the value of parameter index.

Parameters

  index | the index of the invariant factor to return; this must be between 0 and countInvariantFactors()-1 inclusive.

Returns
  the requested invariant factor.

## inverse() [1/2]

GroupExpressionTerm regina::GroupExpressionTerm::inverse | ( |  | ) | const

inline

Returns the inverse of this term.

The inverse has the same generator but a negated exponent.

Note that this term will remain unchanged.

Returns
  the inverse of this term.

## inverse() [2/2]

GroupExpression* regina::GroupExpression::inverse | ( |  | ) | const

Returns a newly created expression that is the inverse of this expression.

The terms will be reversed and the exponents negated.

Returns
  the inverse of this expression.

## inverseHom()

std::unique_ptr<HomMarkedAbelianGroup> regina::HomMarkedAbelianGroup::inverseHom | ( |  | ) | const

Returns the inverse to a HomMarkedAbelianGroup.

If this homomorphism is not invertible, this routine returns the zero homomorphism.

If you are computing with mod-p coefficients, this routine will further require that this invertible map preserves the UCT splitting of the group, i.e., it gives an isomorphism of the tensor product parts and the TOR parts. At present this suffices since we're only using this to construct maps between homology groups in different coordinate systems.

Returns
  the inverse homomorphism, or the zero homomorphism if this is not invertible.

## invert() [1/2]

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

## invert() [2/2]

void regina::GroupExpression::invert | ( |  | ) |

Inverts this expression.

Does not allocate or deallocate anything.

## invEvaluate() [1/2]

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

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

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

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

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

Returns
  the image of this generator in the domain.

## isBoundary()

bool regina::MarkedAbelianGroup::isBoundary | ( | const std::vector< Integer > & | input | ) | const

Given a vector, determines if it represents a boundary in the chain complex.

Python:\n Not available yet. This routine will be made
  accessible to Python in a future release.

Parameters

  input | a vector whose length is M.columns(), where M is one of the matrices that defines the chain complex (see the class notes for details).

Returns
  `true` if and only if the given vector represents a boundary.

## isChainComplex()

bool regina::MarkedAbelianGroup::isChainComplex | ( |  | ) | const

Determines whether or not the defining maps for this group actually give a chain complex.

This is helpful for debugging.

Specifically, this routine returns `true` if and only if M*N = 0 where M and N are the definining matrices.

Returns
  `true` if and only if M*N = 0.

## isChainMap()

bool regina::HomMarkedAbelianGroup::isChainMap | ( | const HomMarkedAbelianGroup & | other | ) | const

Determines whether this and the given homomorphism together form a chain map.

Given two HomMarkedAbelianGroups, you have two diagrams:

    Z^a --N1--> Z^b --M1--> Z^c   Z^g --N3--> Z^h --M3--> Z^i
                      ^                             ^
                      |this.matrix                  |other.matrix
    Z^d --N2--> Z^e --M2--> Z^f   Z^j --N4--> Z^k --M4--> Z^l

If c=g and f=j and M1=N3 and M2=N4, you can ask if these maps commute, i.e., whether you have a map of chain complexes.

Parameters

  other | the other homomorphism to analyse in conjunction with this.

Returns
  true if and only if c=g, M1=N3, f=j, M2=N4, and the diagram commutes.

## isCycle()

bool regina::MarkedAbelianGroup::isCycle | ( | const std::vector< Integer > & | input | ) | const

Given a vector, determines if it represents a cycle in the chain complex.

Python:\n Not available yet. This routine will be made
  accessible to Python in a future release.

Parameters

  input | an input vector in chain complex coordinates.

Returns
  `true` if and only if the given vector represents a cycle.

## isCycleMap()

bool regina::HomMarkedAbelianGroup::isCycleMap | ( |  | ) | const

Is this at least a cycle map? If not, pretty much any further computations you try with this class will be give you nothing more than carefully-crafted garbage.

Technically, this routine only checks that cycles are sent to cycles, since it only has access to three of the four maps you need to verify you have a cycle map.

Returns
  `true` if and only if this is a chain map.

## isEpic()

bool regina::HomMarkedAbelianGroup::isEpic | ( |  | ) | const

inline

Is this an epic homomorphism?

Returns
  true if this homomorphism is epic.

## isIdentity()

bool regina::HomMarkedAbelianGroup::isIdentity | ( |  | ) | const

Is this the identity automorphism?

Returns
  true if and only if the domain and range are defined via the same chain complexes and the induced map on homology is the identity.

## isIsomorphicTo()

bool regina::MarkedAbelianGroup::isIsomorphicTo | ( | const MarkedAbelianGroup & | other | ) | const

inline

Determines whether this and the given abelian group are isomorphic.

Parameters

  other | the group with which this should be compared.

Returns
  `true` if and only if the two groups are isomorphic.

## isIsomorphism()

bool regina::HomMarkedAbelianGroup::isIsomorphism | ( |  | ) | const

inline

Is this an isomorphism?

Returns
  true if this homomorphism is an isomorphism.

## isMonic()

bool regina::HomMarkedAbelianGroup::isMonic | ( |  | ) | const

inline

Is this a monic homomorphism?

Returns
  true if this homomorphism is monic.

## isTrivial() [1/3]

bool regina::AbelianGroup::isTrivial | ( |  | ) | const

inline

Determines whether this is the trivial (zero) group.

Returns
  `true` if and only if this is the trivial group.

## isTrivial() [2/3]

bool regina::MarkedAbelianGroup::isTrivial | ( |  | ) | const

inline

Determines whether this is the trivial (zero) group.

Returns
  `true` if and only if this is the trivial group.

## isTrivial() [3/3]

bool regina::GroupExpression::isTrivial | ( |  | ) | const

inline

Tests whether this is the trivial (unit) word.

No attempt is made to remove redundant terms (so the word `g g^-1` will be treated as non-trivial).

Returns
  `true` if and only if this is the trivial word.

## isValid()

bool regina::GroupPresentation::isValid | ( |  | ) | const

Tests whether all of the relations for the group are indeed words in the generators.

This routine returns `false` if at least one relator uses an out-of-bound generator, and `true` otherwise.

This routine is intended only for sanity checking: you should never have an invalid group presentation in the first place.

Returns
  `true` if and only if all of the relations are words in the generators.

## isZ()

bool regina::AbelianGroup::isZ | ( |  | ) | const

inline

Determines whether this is the infinite cyclic group (Z).

Returns
  `true` if and only if this is the infinite cyclic group.

## isZero()

bool regina::HomMarkedAbelianGroup::isZero | ( |  | ) | const

inline

Is this the zero map?

Returns
  true if this homomorphism is the zero map.

## isZn()

bool regina::AbelianGroup::isZn | ( | unsigned long | n | ) | const

inline

Determines whether this is the non-trivial cyclic group on the given number of elements.

As a special case, if n = 0 then this routine will test for the infinite cyclic group (i.e., it will behave the same as isZ()). If n = 1, then this routine will test for the trivial group (i.e., it will behave the same as isTrivial()).

Parameters

  n | the number of elements of the cyclic group in question.

Returns
  `true` if and only if this is the cyclic group Z_n.

## kernel()

const MarkedAbelianGroup & regina::HomMarkedAbelianGroup::kernel | ( |  | ) | const

inline

Returns the kernel of this homomorphism.

Returns
  the kernel of the homomorphism, as a marked abelian group.

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

## M()

const MatrixInt & regina::MarkedAbelianGroup::M | ( |  | ) | const

inline

Returns the ‘right’ matrix used in defining the chain complex.

Our group was defined as the kernel of M mod the image of N. This is the matrix M.

This is a copy of the matrix M that was originally passed to the class constructor. See the class overview for further details on matrices M and N and their roles in defining the chain complex.

Returns
  a reference to the defining matrix M.

## MarkedAbelianGroup() [1/4]

regina::MarkedAbelianGroup::MarkedAbelianGroup | ( | const MarkedAbelianGroup & | cloneMe | ) |

inline

Creates a clone of the given group.

Parameters

  cloneMe | the group to clone.

## MarkedAbelianGroup() [2/4]

regina::MarkedAbelianGroup::MarkedAbelianGroup | ( | const MatrixInt & | M,
|  | const MatrixInt & | N
| ) |  |

Creates a marked abelian group from a chain complex.

This constructor assumes you're interested in homology with integer coefficents of the chain complex. Creates a marked abelian group given by the quotient of the kernel of M modulo the image of N.

See the class notes for further details.

Precondition
  M.columns() = N.rows().
  The product M*N = 0.

Parameters

  M | the ‘right’ matrix in the chain complex; that is, the matrix that one takes the kernel of when computing homology.
  N | the ‘left’ matrix in the chain complex; that is, the matrix that one takes the image of when computing homology.

## MarkedAbelianGroup() [3/4]

regina::MarkedAbelianGroup::MarkedAbelianGroup | ( | const MatrixInt & | M,
|  | const MatrixInt & | N,
|  | const Integer & | pcoeff
| ) |  |

Creates a marked abelian group from a chain complex with coefficients in Z_p.

Precondition
  M.columns() = N.rows().
  The product M*N = 0.

Parameters

  M | the ‘right’ matrix in the chain complex; that is, the matrix that one takes the kernel of when computing homology.
  N | the ‘left’ matrix in the chain complex; that is, the matrix that one takes the image of when computing homology.
  pcoeff | specifies the coefficient ring, Z_pcoeff. We require pcoeff >= 0. If you know beforehand that pcoeff=0, it's more efficient to use the previous constructor.

## MarkedAbelianGroup() [4/4]

regina::MarkedAbelianGroup::MarkedAbelianGroup | ( | unsigned long | rk,
|  | const Integer & | p
| ) |  |

Creates a free Z_p-module of a given rank using the direct sum of the standard chain complex `0 --> Z –p--> Z --> 0`.

So this group is isomorphic to `n Z_p`. Moreover, if constructed using the previous constructor, M would be zero and N would be diagonal and square with p down the diagonal.

Parameters

  rk | the rank of the group as a Z_p-module. That is, if the group is `n Z_p`, then rk should be n.
  p | describes the type of ring that we use to talk about the "free" module.

## markedAbelianisation() [1/2]

std::unique_ptr< HomMarkedAbelianGroup > regina::HomGroupPresentation::markedAbelianisation | ( |  | ) | const

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

Returns
  the induced map on the abelianizations.

## markedAbelianisation() [2/2]

std::unique_ptr<MarkedAbelianGroup> regina::GroupPresentation::markedAbelianisation | ( |  | ) | const

Computes the abelianisation of this group.

The coordinates in the chain complex correspond to the generators and relators for this group.

Returns
  a newly allocated abelianisation of this group.

## minNumberCycleGens()

unsigned long regina::MarkedAbelianGroup::minNumberCycleGens | ( |  | ) | const

inline

Returns the number of generators of ker(M), where M is one of the defining matrices of the chain complex.

Returns
  the number of generators of ker(M).

## minNumberOfGenerators()

unsigned long regina::MarkedAbelianGroup::minNumberOfGenerators | ( |  | ) | const

inline

Returns the minimum number of generators for the group.

Returns
  the minimum number of generators.

## N()

const MatrixInt & regina::MarkedAbelianGroup::N | ( |  | ) | const

inline

Returns the ‘left’ matrix used in defining the chain complex.

Our group was defined as the kernel of M mod the image of N. This is the matrix N.

This is a copy of the matrix N that was originally passed to the class constructor. See the class overview for further details on matrices M and N and their roles in defining the chain complex.

Returns
  a reference to the defining matrix N.

## nielsenCombine()

bool regina::GroupPresentation::nielsenCombine | ( | unsigned long | i,
|  | unsigned long | j,
|  | long | k,
|  | bool | rightMult = `true`
| ) |  |

Replaces a generator `gi` by either `(gi)(gj)^k` or `(gj)^k(gi)` in the presentation.

It it is the third type of Nielsen move one can apply to a presentation.

This means that, if the new generator `Gi` is the old `(gi)(gj)^k` or `(gj)^k(gi)`, then we can construct the new presentation from the old by replacing occurrences of `Gi` by `(Gi)(gj)^(-k)` or `(gj)^(-k)(Gi)` respectively.

Precondition
  Both i and j are strictly less than countGenerators().

Parameters

  i | indicates the generator to replace.
  j | indicates the generator to combine with `gi`.
  k | indicates the power to which we raise `gj` when performing the replacement; this may be positive or negative (or zero, but this will have no effect).
  rightMult | `true` if we should replace `gi` by `(gi)(gj)^k`, or `false` if we should replace `gi` by `(gj)^k(gi)`.

Returns
  `true` if and only if the nielsen automorphism had an effect on at least one relation.

## nielsenInvert()

bool regina::GroupPresentation::nielsenInvert | ( | unsigned long | i | ) |

Replaces a generator in a presentation by its inverse, and recomputes the appropriate presentation.

This is the second generator type of the automorphism group of a free group.

Precondition
  i is strictly less than countGenerators().

Parameters

  i | indicates the generator to invert.

Returns
  `true` if and only if the Nielsen automorphism had an effect on at least one relation.

## nielsenTransposition()

bool regina::GroupPresentation::nielsenTransposition | ( | unsigned long | i,
|  | unsigned long | j
| ) |  |

Switches the generators in the presentation indexed by i and j respectively, and recomputes the appropriate presentation.

It is one of the standard Nielsen moves, which is the first of three generator types of the automorphism group of a free group.

Precondition
  Both i and j are strictly less than countGenerators().

Parameters

  i | indicates the first of the two generators to switch.
  j | indicates the second of the two generators to switch.

Returns
  `true` if and only if the Nielsen automorphism had an effect on at least one relation.

## operator!=() [1/3]

bool regina::AbelianGroup::operator!= | ( | const AbelianGroup & | other | ) | const

inline

Determines whether this and the given abelian group are non-isomorphic.

Parameters

  other | the group with which this should be compared.

Returns
  `true` if and only if the two groups are non-isomorphic.

## operator!=() [2/3]

bool regina::GroupExpression::operator!= | ( | const GroupExpression & | comp | ) | const

inline

Inequality operator.

Checks to see whether or not these two words represent different literal strings.

Parameters

  comp | the expression to compare against this.

Returns
  `true` if this and the given string literal are not identical.

## operator!=() [3/3]

bool regina::GroupExpressionTerm::operator!= | ( | const GroupExpressionTerm & | other | ) | const

inline

Determines whether this and the given term do not contain identical data.

Parameters

  other | the term with which this term will be compared.

Returns
  `true` if and only if this and the given term do not have both the same generator and exponent.

## operator*()

std::unique_ptr<HomMarkedAbelianGroup> regina::HomMarkedAbelianGroup::operator* | ( | const HomMarkedAbelianGroup & | X | ) | const

Returns the composition of two homomorphisms.

Precondition
  the homomorphisms must be composable, meaning that the range of X must have the same presentation matrices as the domain of this homomorphism.

Parameters

  X | the homomorphism to compose this with.

Returns
  a newly created composite homomorphism.

## operator+=()

bool regina::GroupExpressionTerm::operator+= | ( | const GroupExpressionTerm & | other | ) |

inline

Attempts to merge this term with the given term.

If both terms have the same generator, the two exponents will be added and stored in this term. If the generators are different, this routine will do nothing.

Note that this term might be changed but the given term will remain unchanged.

Parameters

  other | the term to merge with this term.

Returns
  `true` if the two terms were merged into this term, or `false` if the two terms have different generators.

## operator<()

bool regina::GroupExpressionTerm::operator< | ( | const GroupExpressionTerm & | other | ) | const

inline

Imposes an ordering on terms.

Terms are ordered lexigraphically as (generator, exponent) pairs.

Parameters

  other | the term to compare with this.

Returns
  true if and only if this term is lexicographically smaller than other.

## operator<<()

std::ostream& regina::operator<< | ( | std::ostream & | out,
|  | const GroupExpressionTerm & | term
| ) |  |

Writes the given term to the given output stream.

The term will be written in the format `g3^-7`, where in this example the term represents generator number 3 raised to the -7th power.

If the term has exponent 0 or 1, the output format will be appropriately simplified.

Parameters

  out | the output stream to which to write.
  term | the term to write.

Returns
  a reference to the given output stream.

## operator=() [1/3]

GroupExpression & regina::GroupExpression::operator= | ( | const GroupExpression & | cloneMe | ) |

inline

Makes this expression a clone of the given expression.

Parameters

  cloneMe | the expression to clone.

Returns
  a reference to this expression.

## operator=() [2/3]

GroupExpressionTerm & regina::GroupExpressionTerm::operator= | ( | const GroupExpressionTerm & | cloneMe | ) |

inline

Makes this term identical to the given term.

Parameters

  cloneMe | the term whose data will be copied to this term.

Returns
  a reference to this term.

## operator=() [3/3]

GroupPresentation& regina::GroupPresentation::operator= | ( | const GroupPresentation & | cloneMe | ) |

Assignment operator.

Parameters

  cloneMe | the group presentation that this will become a copy of.

Returns
  a reference to this group presentation.

## operator==() [1/3]

bool regina::AbelianGroup::operator== | ( | const AbelianGroup & | other | ) | const

inline

Determines whether this and the given abelian group are isomorphic.

Parameters

  other | the group with which this should be compared.

Returns
  `true` if and only if the two groups are isomorphic.

## operator==() [2/3]

bool regina::GroupExpression::operator== | ( | const GroupExpression & | comp | ) | const

inline

Equality operator.

Checks to see whether or not these two words represent the same literal string.

Parameters

  comp | the expression to compare against this.

Returns
  `true` if this and the given string literal are identical.

## operator==() [3/3]

bool regina::GroupExpressionTerm::operator== | ( | const GroupExpressionTerm & | other | ) | const

inline

Determines whether this and the given term contain identical data.

Parameters

  other | the term with which this term will be compared.

Returns
  `true` if and only if this and the given term have both the same generator and exponent.

## power()

GroupExpression* regina::GroupExpression::power | ( | long | exponent | ) | const

Returns a newly created expression that is this expression raised to the given power.

Note that the given exponent may be positive, zero or negative.

Parameters

  exponent | the power to which this expression should be raised.

Returns
  this expression raised to the given power.

## prettyRewriting()

bool regina::GroupPresentation::prettyRewriting | ( |  | ) |

An entirely cosmetic re-writing of the presentation, which is fast and superficial.

See prettyRewritingDetail() for further details on what this routine does.

Returns
  `true` if and only if the choice of generators for the group has changed. You can call prettyRewritingDetail() to get the the isomorphism.

## prettyRewritingDetail()

std::unique_ptr<HomGroupPresentation> regina::GroupPresentation::prettyRewritingDetail | ( |  | ) |

An entirely cosmetic re-writing of the presentation, which is fast and superficial.

1. If there are any length 1 relators, those generators are deleted, and the remaining relators simplified.
2. It sorts the relators by number of generator indices that appear, followed by relator numbers (lexico) followed by relator length.
3. inverts relators if net sign of the generators is negative.
4. Given each generator, it looks for the smallest word where that generator appears with non-zero weight. If negative weight, it inverts that generator.
5. It cyclically permutes relators to start with smallest gen.

If this routine does return a homomorphism (because the choice of generators was changed), then this homomorphsm will in fact be a declared isomorphism. See the HomGroupPresentation class notes for details on what this means.

Todo:
  As a final step, make elementary simplifications to aid in seeing standard relators like commutators.

Returns
  a newly allocated homomorphism describing the map from the original presentation to the new presentation, or a null pointer if the choice of generators did not change.

## proliferateRelators()

void regina::GroupPresentation::proliferateRelators | ( | unsigned long | depth = `1` | ) |

A routine to help escape local wells when simplifying presentations, which may be useful when small cancellation theory can't find the simplest relators.

Given a presentation <g_i | r_i>, this routine appends consequences of the relators {r_i} to the presentation that are of the form ab, where both a and b are cyclic permutations of relators from the collection {r_i}.

Passing depth=1 means it will only form products of two relators. Depth=2 means products of three, etc. Depth=4 is typically the last depth before the exponential growth of the operation grows out of hand. It also conveniently trivializes all the complicated trivial group presentations that we've come across so far.

Warning
  Do not call this routine with depth n before having called it at depth n-1 first. Depth=0 is invalid, and depth=1 should be your first call to this routine. This routine gobbles up an exponential amount of memory (exponential in your presentation size times n). So do be careful when using it.

Parameters

  depth | controls the depth of the proliferation, as described above; this must be strictly positive.

## range() [1/2]

const GroupPresentation & regina::HomGroupPresentation::range | ( |  | ) | const

inline

The range of the map.

Returns
  a reference to the range.

## range() [2/2]

const MarkedAbelianGroup & regina::HomMarkedAbelianGroup::range | ( |  | ) | const

inline

Returns the range of this homomorphism.

Returns
  the range that was used to define the homomorphism.

## rank() [1/2]

unsigned regina::AbelianGroup::rank | ( |  | ) | const

inline

Returns the rank of the group.

This is the number of included copies of Z.

Returns
  the rank of the group.

## rank() [2/2]

unsigned long regina::MarkedAbelianGroup::rank | ( |  | ) | const

inline

Returns the rank of the group.

This is the number of included copies of Z.

Returns
  the rank of the group.

## rankCC()

unsigned long regina::MarkedAbelianGroup::rankCC | ( |  | ) | const

inline

Returns the rank of the chain complex supporting the homology computation.

In the description of this class, this is also given by M.columns() and N.rows() from the constructor that takes as input two matrices, M and N.

Returns
  the rank of the chain complex.

## recogniseGroup()

std::string regina::GroupPresentation::recogniseGroup | ( | bool | moreUtf8 = `false` | ) | const

Attempts to recognise the group corresponding to this presentation.

This routine is much more likely to be successful if you have already called intelligentSimplify().

Currently, the groups this routine recognises include: the trivial group, abelian groups, free groups, extensions over the integers, and free products of any group the algorithm can recognise (inductively).

The string returned from this routine may use some unicode characters, which will be encoding using UTF-8. If moreUtf8 is passed as `false` then unicode will be used sparingly; if moreUtf8 is `true` then unicode will be use more liberally, resulting in strings that look nicer but require more complex fonts to be available on the user's machine.

Examples of the format of the returned string are:

- `0` for the trivial group;
- `Z_n` for cyclic groups with n > 1;
- `Free(n)` for free groups with n > 1 generators - see AbelianGroup::str() for how abelian groups are presented;
- `FreeProduct(G1, G2, ... , Gk)` for free products, where one replaces G1 through Gk by text strings representing the free summands;

- `Z~G w/ monodromy H` for extensions over Z, where G is a description of the kernel of the homomorphism to the integers, and H is a text string representing the monodromy - see HomMarkedAbelianGroup.str() for details on how these are presented.

  Todo:
    Feature (long-term): Make this recognition more effective.

Returns
  a simple string representation of the group if it is recognised, or an empty string if the group is not recognised.

## reducedMatrix()

const MatrixInt & regina::HomMarkedAbelianGroup::reducedMatrix | ( |  | ) | const

inline

Returns the internal reduced matrix representing the homomorphism.

This is where the rows/columns of the matrix represent first the free generators, then the torsion summands in the order of the invariant factors:

            Z^d + Z_{d0} + ... + Z_{dk}

where:

- d is the number of free generators, as returned by rank();
- d1, ..., dk are the invariant factors that describe the torsion elements of the group, where 1 < d1 | d2 | ... | dk.

Returns
  a copy of the internal representation of the homomorphism.

## relabellingsThisToOther()

std::list< std::map< unsigned long, GroupExpressionTerm > > regina::GroupExpression::relabellingsThisToOther | ( | const GroupExpression & | other,
|  | bool | cyclic = `false`
| ) |  | const

Determines whether or not one can relabel the generators in this word to obtain the given other word.

If so, returns a non-empty list of all such relabellings. If not, returns an empty list.

Relabellings are partially-defined permutations on the generator set, also allowing for possible inversions if cyclic is `true`.

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:
  Change this to use less heavyweight types and less deep copying.

Precondition
  If cyclic is `true`, then both this word and other have been cyclically reduced.

Python:\n Not present.

Parameters

  other | the word to compare against this.
  cyclic | if `false` we get a list of exact relabellings from this word to other. If `true`, it can be up to cyclic permutation and inversion.

Returns
  a list of permutations, implemented as maps from generator indices of this word to generator indices of other.

## relation()

const GroupExpression & regina::GroupPresentation::relation | ( | size_t | index | ) | const

inline

Returns the relation at the given index in this group presentation.

The relation will be of the form `expresson = 1`.

Parameters

  index | the index of the desired relation; this must be between 0 and countRelations()-1 inclusive.

Returns
  the expression that the requested relation sets to 1; for instance, if the relation is `g1^2 g2 = 1` then this will be the expression `g1^2 g2`.

## relatorLength()

size_t regina::GroupPresentation::relatorLength | ( |  | ) | const

inline

The sum of the word lengths of the relators.

Word lengths are computing using GroupExpression::wordLength(). Used as a coarse measure of the complexity of the presentation.

Returns
  the sum of word lengths.

## replaceTorsion()

void regina::AbelianGroup::replaceTorsion | ( | const MatrixInt & | matrix | ) |

protected

Replaces the torsion elements of this group with those in the abelian group represented by the given Smith normal form presentation matrix.

Any zero columns in the matrix will also be added to the rank as additional copies of Z. Note that preexisting torsion elements will be deleted, but preexisting rank will not.

Precondition
  The given matrix is in Smith normal form, with the diagonal consisting of a series of positive, non-decreasing integers followed by zeroes.

Parameters

  matrix | a matrix containing the Smith normal form presentation matrix for the new torsion elements, where each column represents a generator and each row a relation.

## simplify()

bool regina::GroupExpression::simplify | ( | bool | cyclic = `false` | ) |

Simplifies this expression.

Adjacent powers of the same generator will be combined, and terms with an exponent of zero will be removed. Note that it is not assumed that the underlying group is abelian.

You may declare that the expression is cyclic, in which case it is assumed that terms may be moved from the back to the front and vice versa. Thus expression `g1 g2 g1 g2 g1` simplifies to `g1^2 g2 g1 g2` if it is cyclic, but does not simplify at all if it is not cyclic.

Parameters

  cyclic | `true` if and only if the expression may be assumed to be cyclic.

Returns
  `true` if and only if this expression was changed.

## simplifyWord()

bool regina::GroupPresentation::simplifyWord | ( | GroupExpression & | input | ) | const

Uses small cancellation theory to reduce the input word, using the current presentation of the group.

The input word will be modified directly.

Warning
  This routine is only as good as the relator table for the group. You might want to consider running intelligentSimplify(), possibly in concert with proliferateRelators(), before using this routine for any significant tasks.

Parameters

  input | is the word you would like to simplify. This must be a word in the generators of this group.

Returns
  `true` if and only if the input word was modified.

## smallCancellation() [1/2]

bool regina::HomGroupPresentation::smallCancellation | ( |  | ) |

Simplifies the domain and range using only small cancellation theory.

Returns
  `true` if and only if either presentation was changed.

## smallCancellation() [2/2]

bool regina::GroupPresentation::smallCancellation | ( |  | ) |

Attempts to simplify the group presentation using only small cancellation theory.

See smallCancellationDetail() for further details on how the simplification is done.

Returns
  `true` if and only if the group presentation was changed. You can call smallCancellationDetail() to get the isomorphism.

## smallCancellationDetail()

std::unique_ptr<HomGroupPresentation> regina::GroupPresentation::smallCancellationDetail | ( |  | ) |

Attempts to simplify the group presentation using small cancellation theory.

The simplification method is based on the Dehn algorithm for hyperbolic groups, i.e. small cancellation theory. This means we look to see if part of one relator can be used to simplify others. If so, make the substitution and simplify. We continue until no more presentation-shortening substitutions are available. We follow that by killing any available generators using words where generators appear a single time.

If this routine does return a homomorphism (because the presentation was changed), then this homomorphsm will in fact be a declared isomorphism. See the HomGroupPresentation class notes for details on what this means.

Todo:
  Optimise (long-term): This routine could use some small tweaks - recognition of utility of some score==0 moves, such as commutators, for example.

Returns
  a newly allocated homomorphism describing the reduction map from the original presentation to the new presentation, or a null pointer if this presentation was not changed.

## snfRep()

std::vector<Integer> regina::MarkedAbelianGroup::snfRep | ( | const std::vector< Integer > & | v | ) | const

Expresses the given vector as a combination of free and torsion generators.

This answer is coordinate dependant, meaning the answer may change depending on how the Smith Normal Form is computed.

Recall that this marked abelian was defined by matrices M and N with M*N=0; suppose that M is an m by l matrix and N is an l by n matrix. This abelian group is then the quotient ker(M)/img(N) in Z^l.

When it is constructed, this group is computed to be isomorphic to some Z_{d0} + ... + Z_{dk} + Z^d, where:

- d is the number of free generators, as returned by rank();
- d1, ..., dk are the invariant factors that describe the torsion elements of the group, where 1 < d1 | d2 | ... | dk.

This routine takes a single argument v, which must be a vector in Z^l.

If v belongs to ker(M), this routine describes how it projects onto the group ker(M)/img(N). Specifically, it returns a vector of length d + k, where:

- The first k elements describe the projection of v to the torsion component Z_{d1} + ... + Z_{dk}. These elements are returned as non-negative integers modulo d1, ..., dk respectively.
- The remaining d elements describe the projection of v to the free component Z^d.

In other words, suppose v belongs to ker(M) and snfRep(v) returns the vector (b1, ..., bk, a1, ..., ad). Suppose furthermore that the free generators returned by freeRep(0..(d-1)) are f1, ..., fd respectively, and that the torsion generators returned by torsionRep(0..(k-1)) are t1, ..., tk respectively. Then v = b1.t1 + ... + bk.tk + a1.f1 + ... + ad.fd modulo img(N).

If v does not belong to ker(M), this routine simply returns the empty vector.

Warning
  The return value may change from version to version of Regina, as it depends on the choice of Smith normal form.

Precondition
  Vector v has length M.columns(), or equivalently N.rows().

Python:\n Both v and the return value are python lists.

Parameters

  v | a vector of length M.columns(). M.columns() is also rankCC().

Returns
  a vector that describes v in the standard Z_{d1} + ... + Z_{dk} + Z^d form, or the empty vector if v is not in the kernel of M. k+d is equal to minNumberOfGenerators().

## startElement() [1/2]

virtual void regina::XMLAbelianGroupReader::startElement | ( | const std::string & | tagName,
|  | const regina::xml::XMLPropertyDict & | tagProps,
|  | XMLElementReader * | parentReader
| ) |  |

virtual

Signifies that parsing of this XML element is beginning.

The default implementation does nothing.

Parameters

  tagName | the name of the opening tag for this element.
  tagProps | the properties associated with the opening tag.
  parentReader | the reader currently parsing the parent XML element, or 0 if this is the top-level element. If this paraneter is non-zero, it is guaranteed that startSubElement() has already been called upon the parent reader.

Reimplemented from regina::XMLElementReader.

## startElement() [2/2]

virtual void regina::XMLGroupPresentationReader::startElement | ( | const std::string & | tagName,
|  | const regina::xml::XMLPropertyDict & | tagProps,
|  | XMLElementReader * | parentReader
| ) |  |

virtual

Signifies that parsing of this XML element is beginning.

The default implementation does nothing.

Parameters

  tagName | the name of the opening tag for this element.
  tagProps | the properties associated with the opening tag.
  parentReader | the reader currently parsing the parent XML element, or 0 if this is the top-level element. If this paraneter is non-zero, it is guaranteed that startSubElement() has already been called upon the parent reader.

Reimplemented from regina::XMLElementReader.

## startSubElement()

virtual XMLElementReader* regina::XMLGroupPresentationReader::startSubElement | ( | const std::string & | subTagName,
|  | const regina::xml::XMLPropertyDict & | subTagProps
| ) |  |

virtual

Signifies that a subelement of this XML element is about to be parsed.

The default implementation returns a new XMLElementReader which can be used to ignore the subelement completely.

Parameters

  subTagName | the name of the subelement opening tag.
  subTagProps | the properties associated with the subelement opening tag.

Returns
  a newly created element reader that will be used to parse the subelement. This class should not take care of the new reader's destruction; that will be done by the parser.

Reimplemented from regina::XMLElementReader.

## substitute()

bool regina::GroupExpression::substitute | ( | unsigned long | generator,
|  | const GroupExpression & | expansion,
|  | bool | cyclic = `false`
| ) |  |

Replaces every occurrence of the given generator with the given substite expression.

If the given generator was found, the expression will be simplified once the substitution is complete.

Parameters

  generator | the generator to be replaced.
  expansion | the substitute expression that will replace every occurrence of the given generator.
  cyclic | `true` if and only if the expression may be assumed to be cyclic; see simplify() for further details.

Returns
  `true` if and only if any substitutions were made.

## term() [1/2]

GroupExpressionTerm& regina::GroupExpression::term | ( | size_t | index | ) |

Returns the term at the given index in this expression.

Index 0 represents the first term, index 1 represents the second term and so on.

Warning
  This routine is O(n) where n is the number of terms in this expression.

Parameters

  index | the index of the term to return; this must be between 0 and countTerms()-1 inclusive.

Returns
  the requested term.

## term() [2/2]

const GroupExpressionTerm& regina::GroupExpression::term | ( | size_t | index | ) | const

Returns a constant reference to the term at the given index in this expression.

Index 0 represents the first term, index 1 represents the second term and so on.

Warning
  This routine is O(n) where n is the number of terms in this expression.

Python:\n Not present; only the non-const version of this
  routine is available.

Parameters

  index | the index of the term to return; this must be between 0 and countTerms()-1 inclusive.

Returns
  the requested term.

## terms() [1/2]

std::list< GroupExpressionTerm > & regina::GroupExpression::terms | ( |  | ) |

inline

Returns the list of terms in this expression.

These are the actual terms stored internally; any modifications made to this list will show up in the expression itself.

For instance, the expression `g1^2 g3^-1 g6` has list consisting of three terms `g1^2`, `g3^-1` and `g6^1` in that order.

Python:\n Not present; only the const version of this
  routine is available.

Returns
  the list of terms.

## terms() [2/2]

const std::list< GroupExpressionTerm > & regina::GroupExpression::terms | ( |  | ) | const

inline

Returns a constant reference to the list of terms in this expression.

For instance, the expression `g1^2 g3^-1 g6` has list consisting of three terms `g1^2`, `g3^-1` and `g6^1` in that order.

Python:\n This routine returns a python list of copied
  GroupExpressionTerm objects. In particular, modifying this list or the terms within it will not modify the group expression from which they came.

Returns
  the list of terms.

## torsionInclusion()

std::unique_ptr<HomMarkedAbelianGroup> regina::MarkedAbelianGroup::torsionInclusion | ( |  | ) | const

Returns a HomMarkedAbelianGroup representing the inclusion of the torsion subgroup into this group.

## torsionRank() [1/4]

unsigned regina::AbelianGroup::torsionRank | ( | const Integer & | degree | ) | const

Returns the rank in the group of the torsion term of given degree.

If the given degree is d, this routine will return the largest m for which mZ_d is a subgroup of this group.

For instance, if this group is Z_6+Z_12, the torsion term of degree 2 has rank 2 (one occurrence in Z_6 and one in Z_12), and the torsion term of degree 4 has rank 1 (one occurrence in Z_12).

Precondition
  The given degree is at least 2.

Parameters

  degree | the degree of the torsion term to query.

Returns
  the rank in the group of the given torsion term.

## torsionRank() [2/4]

unsigned long regina::MarkedAbelianGroup::torsionRank | ( | const Integer & | degree | ) | const

Returns the rank in the group of the torsion term of given degree.

If the given degree is d, this routine will return the largest m for which mZ_d is a subgroup of this group.

For instance, if this group is Z_6+Z_12, the torsion term of degree 2 has rank 2 (one occurrence in Z_6 and one in Z_12), and the torsion term of degree 4 has rank 1 (one occurrence in Z_12).

Precondition
  The given degree is at least 2.

Parameters

  degree | the degree of the torsion term to query.

Returns
  the rank in the group of the given torsion term.

## torsionRank() [3/4]

unsigned regina::AbelianGroup::torsionRank | ( | unsigned long | degree | ) | const

inline

Returns the rank in the group of the torsion term of given degree.

If the given degree is d, this routine will return the largest m for which mZ_d is a subgroup of this group.

For instance, if this group is Z_6+Z_12, the torsion term of degree 2 has rank 2 (one occurrence in Z_6 and one in Z_12), and the torsion term of degree 4 has rank 1 (one occurrence in Z_12).

Precondition
  The given degree is at least 2.

Parameters

  degree | the degree of the torsion term to query.

Returns
  the rank in the group of the given torsion term.

## torsionRank() [4/4]

unsigned long regina::MarkedAbelianGroup::torsionRank | ( | unsigned long | degree | ) | const

inline

Returns the rank in the group of the torsion term of given degree.

If the given degree is d, this routine will return the largest m for which mZ_d is a subgroup of this group.

For instance, if this group is Z_6+Z_12, the torsion term of degree 2 has rank 2 (one occurrence in Z_6 and one in Z_12), and the torsion term of degree 4 has rank 1 (one occurrence in Z_12).

Precondition
  The given degree is at least 2.

Parameters

  degree | the degree of the torsion term to query.

Returns
  the rank in the group of the given torsion term.

## torsionRep()

std::vector<Integer> regina::MarkedAbelianGroup::torsionRep | ( | unsigned long | index | ) | const

Returns the requested generator of the torsion subgroup but represented in the original chain complex defining the group.

As described in the class overview, this marked abelian group is defined by matrices M and N where M*N = 0. If M is an m by l matrix and N is an l by n matrix, then this routine returns the (index)th torsion generator of ker(M)/img(N) in Z^l.

Python:\n The return value will be a python list.

Warning
  The return value may change from version to version of Regina, since it depends on the choice of Smith normal form.

Parameters

  index | specifies which generator in the torsion subgroup; this must be at least 0 and strictly less than the number of non-trivial invariant factors. If not, you receive an empty vector.

Returns
  the coordinates of the generator in the nullspace of M; this vector will have length M.columns() (or equivalently, N.rows()).

## torsionSubgroup() [1/2]

std::unique_ptr<MarkedAbelianGroup> regina::MarkedAbelianGroup::torsionSubgroup | ( |  | ) | const

Returns a MarkedAbelianGroup representing the torsion subgroup of this group.

## torsionSubgroup() [2/2]

std::unique_ptr<HomMarkedAbelianGroup> regina::HomMarkedAbelianGroup::torsionSubgroup | ( |  | ) | const

Returns a HomMarkedAbelianGroup representing the induced map on the torsion subgroups.

## toTeX() [1/2]

std::string regina::GroupExpression::toTeX | ( |  | ) | const

Returns a TeX representation of this expression.

See writeTeX() for details on how this is formed.

Returns
  a TeX representation of this expression.

## toTeX() [2/2]

std::string regina::GroupPresentation::toTeX | ( |  | ) | const

Returns a TeX representation of this group presentation.

See writeTeX() for details on how this is formed.

Returns
  a TeX representation of this group presentation.

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

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

## wordLength()

size_t regina::GroupExpression::wordLength | ( |  | ) | const

inline

Returns the length of the word, i.e.

the number of letters with exponent +1 or -1 for which this word is expressable as a product.

For instance, the expression `g1^2 g3^-1 g6` is a word of length four. See also countTerms().

No attempt is made to remove redundant terms (so the word `g g^-1` will count as length two).

Returns
  the length of the word.

## writeAsBoundary()

std::vector<Integer> regina::MarkedAbelianGroup::writeAsBoundary | ( | const std::vector< Integer > & | input | ) | const

Expresses the given vector as a boundary in the chain complex (if the vector is indeed a boundary at all).

This routine uses chain complex coordinates for both the input and the return value.

Warning
  If you're using mod-p coefficients and if your element projects to a non-trivial element of TOR, then Nv != input as elements of TOR aren't in the image of N. In this case, input-Nv represents the projection to TOR.
  The return value may change from version to version of Regina, since it depends on the choice of Smith normal form.

Python:\n Not available yet. This routine will be made
  accessible to Python in a future release.

Returns
  a length zero vector if the input is not a boundary; otherwise a vector v such that `Nv=input`.

## writeReducedMatrix()

void regina::HomMarkedAbelianGroup::writeReducedMatrix | ( | std::ostream & | out | ) | const

Writes a human-readable version of the reduced matrix to the given output stream.

This is a description of the homomorphism in some specific coordinates at present only meant to be internal to HomMarkedAbelianGroup. At present, these coordinates have the torsion factors of the group appearing first, followed by the free factors.

Python:\n The out argument is missing; instead this is
  assumed to be standard output.

Parameters

  out | the output stream.

## writeTeX() [1/2]

void regina::GroupExpression::writeTeX | ( | std::ostream & | out | ) | const

Writes a TeX represesentation of this expression to the given output stream.

The text representation will be of the form `g_2^4 g_{13}^{-5} g_4`.

Python:\n The parameter out does not exist;
  standard output will be used.

Parameters

  out | the output stream to which to write.

## writeTeX() [2/2]

void regina::GroupPresentation::writeTeX | ( | std::ostream & | out | ) | const

Writes a TeX represesentation of this group presentation to the given output stream.

The output will be of the form < generators | relators >. There will be no final newline.

Python:\n The parameter out does not exist;
  standard output will be used.

Parameters

  out | the output stream to which to write.

## writeText()

void regina::GroupExpression::writeText | ( | std::ostream & | out,
|  | bool | shortword = `false`,
|  | bool | utf8 = `false`
| ) |  | const

Writes a text representation of this expression to the given output stream, using either numbered generators or alphabetic generators.

The text representation will be of the form `g2^4 g13^-5 g4`. If the shortword flag is `true`, it will assume your word is in an alphabet of no more than 26 letters, and will write the word using lower-case ASCII, i.e., `c^4 n^-5 e`. If the utf8 flag is `true`, all exponents will be written using superscript characters encoded in UTF-8.

Precondition
  If shortword is `true`, the number of generators in the corresponding group must be 26 or fewer.

Python:\n The parameter out does not exist;
  standard output will be used.

Parameters

  out | the output stream to which to write.
  shortword | indicates whether to use numbered or alphabetic generators, as described above.
  utf8 | `true` if exponents should be written using unicode superscript characters, or `false` if they should be written using a caret (^) symbol.

## writeTextCompact()

void regina::GroupPresentation::writeTextCompact | ( | std::ostream & | out | ) | const

Writes a compact represesentation of this group to the given output stream.

The output will be of the form < generators | relators >. The full relations will be included, and the entire output will be written on a single line. There will be no final newline.

Python:\n The parameter out does not exist;
  standard output will be used.

Parameters

  out | the output stream to which to write.

## writeTextLong() [1/3]

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

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

Python:\n Not present.

Parameters

  out | the output stream to which to write.

## writeTextLong() [2/3]

void regina::HomMarkedAbelianGroup::writeTextLong | ( | std::ostream & | out | ) | const

A more detailed text representation of the homomorphism.

Parameters

  out | the stream to write to.

## writeTextLong() [3/3]

void regina::GroupPresentation::writeTextLong | ( | std::ostream & | out | ) | const

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

Python:\n Not present.

Parameters

  out | the output stream to which to write.

## writeTextShort() [1/6]

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

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

Python:\n Not present.

Parameters

  out | the output stream to which to write.

## writeTextShort() [2/6]

void regina::GroupExpression::writeTextShort | ( | std::ostream & | out | ) | const

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

The text representation will be of the form `g2^4 g13^-5 g4`.

Python:\n Not present.

Parameters

  out | the output stream to which to write.

## writeTextShort() [3/6]

void regina::HomMarkedAbelianGroup::writeTextShort | ( | std::ostream & | out | ) | const

Short text representation.

This will state some basic properties of the homomorphism, such as:

- whether the map is the identity;
- whether the map is an isomorphism;
- whether the map is monic or epic;
- if it is not monic, describes the kernel;
- if it is not epic, describes the co-kernel;
- if it is neither monic nor epic, describes the image.

Parameters

  out | the stream to write to.

## writeTextShort() [4/6]

void regina::GroupPresentation::writeTextShort | ( | std::ostream & | out | ) | const

inline

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

Python:\n Not present.

Parameters

  out | the output stream to which to write.

## writeTextShort() [5/6]

void regina::MarkedAbelianGroup::writeTextShort | ( | std::ostream & | out,
|  | bool | utf8 = `false`
| ) |  | const

The text representation will be of the form `3 Z + 4 Z_2 + Z_120`.

The torsion elements will be written in terms of the invariant factors of the group, as described in the MarkedAbelianGroup notes.

Parameters

  out | the stream to write to.
  utf8 | if `true`, then richer unicode characters will be used to make the output more pleasant to read. In particular, the output will use subscript digits and the blackboard bold Z.

## writeTextShort() [6/6]

void regina::AbelianGroup::writeTextShort | ( | std::ostream & | out,
|  | bool | utf8 = `false`
| ) |  | const

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

The text representation will be of the form `3 Z + 4 Z_2 + Z_120`. The torsion elements will be written in terms of the invariant factors of the group, as described in the AbelianGroup notes.

Python:\n Not present.

Parameters

  out | the output stream to which to write.
  utf8 | if `true`, then richer unicode characters will be used to make the output more pleasant to read. In particular, the output will use subscript digits and the blackboard bold Z.

## writeXMLData() [1/3]

void regina::AbelianGroup::writeXMLData | ( | std::ostream & | out | ) | const

Writes a chunk of XML containing this abelian group.

Python:\n Not present.

Parameters

  out | the output stream to which the XML should be written.

## writeXMLData() [2/3]

void regina::GroupExpression::writeXMLData | ( | std::ostream & | out | ) | const

Writes a chunk of XML containing this expression.

Python:\n Not present.

Parameters

  out | the output stream to which the XML should be written.

## writeXMLData() [3/3]

void regina::GroupPresentation::writeXMLData | ( | std::ostream & | out | ) | const

Writes a chunk of XML containing this group presentation.

Python:\n Not present.

Parameters

  out | the output stream to which the XML should be written.

## XMLAbelianGroupReader()

regina::XMLAbelianGroupReader::XMLAbelianGroupReader | ( |  | ) |

inline

Creates a new abelian group reader.

## XMLGroupPresentationReader()

regina::XMLGroupPresentationReader::XMLGroupPresentationReader | ( |  | ) |

inline

Creates a new group presentation reader.

## ~GroupPresentation()

regina::GroupPresentation::~GroupPresentation | ( |  | ) |

inline

Destroys the group presentation.

All relations that are stored will be deallocated.

## ~HomGroupPresentation()

regina::HomGroupPresentation::~HomGroupPresentation | ( |  | ) |

inline

Destroys the group homomorphism.

## ~HomMarkedAbelianGroup()

regina::HomMarkedAbelianGroup::~HomMarkedAbelianGroup | ( |  | ) |

inline

Destructor.

## Variable Documentation

## exponent

long regina::GroupExpressionTerm::exponent

The exponent to which the generator is raised.

## generator

unsigned long regina::GroupExpressionTerm::generator

The number that identifies the generator in this term.

## invariantFactors

std::multiset<Integer> regina::AbelianGroup::invariantFactors

protected

The invariant factors d0,...,dn as described in the AbelianGroup notes.

## invertB

bool regina::GroupPresentation::NWordSubstitutionData::invertB

Invert B before making the substitution?

## nGenerators

unsigned long regina::GroupPresentation::nGenerators

protected

The number of generators.

## rank_

unsigned regina::AbelianGroup::rank_

protected

The rank of the group (the number of Z components).

## relations

std::vector<GroupExpression*> regina::GroupPresentation::relations

protected

The relations between the generators.

## score

long int regina::GroupPresentation::NWordSubstitutionData::score

The score, i.e., the decrease in the word letter count provided this substitution is made.

## start_from

unsigned long regina::GroupPresentation::NWordSubstitutionData::start_from

Where in B do we start?

## start_sub_at

unsigned long regina::GroupPresentation::NWordSubstitutionData::start_sub_at

Where in A do we start?

## sub_length

unsigned long regina::GroupPresentation::NWordSubstitutionData::sub_length

The number of letters from B to use.

Copyright © 1999-2016, 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@maths.uq.edu.au).