Regina Calculation Engine
Classes | Typedefs | Functions | Variables | Friends
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 Integerregina::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...
 
GroupExpressionTermregina::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...
 
GroupExpressionregina::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...
 
GroupExpressionTermregina::GroupExpression::term (size_t index)
 Returns the term at the given index in this expression. More...
 
const GroupExpressionTermregina::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...
 
GroupExpressionregina::GroupExpression::inverse () const
 Returns a newly created expression that is the inverse of this expression. More...
 
void regina::GroupExpression::invert ()
 Inverts this expression. More...
 
GroupExpressionregina::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...
 
GroupPresentationregina::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 GroupExpressionregina::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< HomGroupPresentationregina::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< HomGroupPresentationregina::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< AbelianGroupregina::GroupPresentation::abelianisation () const
 Computes the abelianisation of this group. More...
 
std::unique_ptr< MarkedAbelianGroupregina::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< HomGroupPresentationregina::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< HomGroupPresentationregina::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< HomGroupPresentationregina::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 GroupPresentationregina::HomGroupPresentation::domain () const
 The domain of the map. More...
 
const GroupPresentationregina::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< HomGroupPresentationregina::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< HomMarkedAbelianGroupregina::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 Integerregina::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< Integerregina::MarkedAbelianGroup::freeRep (unsigned long index) const
 Returns the requested free generator in the original chain complex defining the group. More...
 
std::vector< Integerregina::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< Integerregina::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< Integerregina::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< Integerregina::MarkedAbelianGroup::cycleProjection (const std::vector< Integer > &ccelt) const
 Projects an element of the chain complex to the subspace of cycles. More...
 
std::vector< Integerregina::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< Integerregina::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< Integerregina::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< Integerregina::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< Integerregina::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 MatrixIntregina::MarkedAbelianGroup::M () const
 Returns the ‘right’ matrix used in defining the chain complex. More...
 
const MatrixIntregina::MarkedAbelianGroup::N () const
 Returns the ‘left’ matrix used in defining the chain complex. More...
 
const Integerregina::MarkedAbelianGroup::coefficients () const
 Returns the coefficients used for the computation of homology. More...
 
std::unique_ptr< MarkedAbelianGroupregina::MarkedAbelianGroup::torsionSubgroup () const
 Returns a MarkedAbelianGroup representing the torsion subgroup of this group. More...
 
std::unique_ptr< HomMarkedAbelianGroupregina::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 MarkedAbelianGroupregina::HomMarkedAbelianGroup::kernel () const
 Returns the kernel of this homomorphism. More...
 
const REGINA_INLINE_REQUIRED MarkedAbelianGroupregina::HomMarkedAbelianGroup::cokernel () const
 Returns the cokernel of this homomorphism. More...
 
const REGINA_INLINE_REQUIRED MarkedAbelianGroupregina::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 MarkedAbelianGroupregina::HomMarkedAbelianGroup::domain () const
 Returns the domain of this homomorphism. More...
 
const MarkedAbelianGroupregina::HomMarkedAbelianGroup::range () const
 Returns the range of this homomorphism. More...
 
const MatrixIntregina::HomMarkedAbelianGroup::definingMatrix () const
 Returns the defining matrix for the homomorphism. More...
 
const MatrixIntregina::HomMarkedAbelianGroup::reducedMatrix () const
 Returns the internal reduced matrix representing the homomorphism. More...
 
std::vector< Integerregina::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< Integerregina::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< HomMarkedAbelianGroupregina::HomMarkedAbelianGroup::inverseHom () const
 Returns the inverse to a HomMarkedAbelianGroup. More...
 
std::unique_ptr< HomMarkedAbelianGroupregina::HomMarkedAbelianGroup::operator* (const HomMarkedAbelianGroup &X) const
 Returns the composition of two homomorphisms. More...
 
std::unique_ptr< HomMarkedAbelianGroupregina::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 AbelianGroupregina::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 GroupPresentationregina::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 XMLElementReaderregina::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< Integerregina::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

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

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

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

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

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

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

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
cloneMethe 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
Mthe ‘right’ matrix in the chain complex; that is, the matrix that one takes the kernel of when computing homology.
Nthe ‘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
Mthe ‘right’ matrix in the chain complex; that is, the matrix that one takes the kernel of when computing homology.
Nthe ‘left’ matrix in the chain complex; that is, the matrix that one takes the image of when computing homology.
pthe 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
numToAddthe 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
groupthe 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
presentationa 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
extraRankthe 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
relthe 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
inputa 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
inputa 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
termthe 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
generatorthe number of the generator corresponding to the new term.
exponentthe 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
termthe 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
generatorthe number of the generator corresponding to the new term.
exponentthe 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
wordthe 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
wordthe 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
degreed, where we are adding copies of Z_d to the torsion.
multthe 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
degreed, where we are adding copies of Z_d to the torsion.
multthe 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
torsiona 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
CCrepa 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
SNFRepa 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
SNFRepspecifies 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
inputthe 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
ibetween 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
ccelta 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
ccindxthe 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
subTagNamethe name of the subelement closing tag.
subReaderthe 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
otherthe 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
inputan 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
inputan 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
argan 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
ithe 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
indexthe 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
indexspecifies 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
indexthe 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 ( )
inlinevirtual

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

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
cloneMethe 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
inputthe input string that is to be interpreted.
validused 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
cloneMea 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
newGenthe number that identifies the generator in the new term.
newExpthe 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
cloneMethe 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
nGensthe number of generators.
relsa 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
domainthe domain of the homomorphism.
rangethe range of the homomorphism.
mapa vector of length g, where g is the number of generators of the domain, and where this homomorphism sends the ith generator of the domain to the element map[i] of the range.
Python:\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
domainthe domain of the homomorphism.
rangethe range of the homomorphism.
mapa vector of length g, where g is the number of generators of the domain, and where this homomorphism sends the ith generator of the domain to the element map[i] of the range.
inva vector of length k where k is the number of generators of the range, and where the inverse homomorphism sends the ith generator of the range to the element inv[i] of the domain.

◆ 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
groupForIdentityboth 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
cloneMethe presentation to clone.

◆ HomMarkedAbelianGroup() [1/2]

regina::HomMarkedAbelianGroup::HomMarkedAbelianGroup ( const HomMarkedAbelianGroup h)

Copy constructor.

Parameters
hthe 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
domthe domain group.
ranthe range group.
matthe 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
otherthe 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
charsthe 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
indexthe 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
indexthe 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
argan 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
ithe 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
inputa 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
otherthe 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
inputan 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
otherthe 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
nthe 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
cloneMethe 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
Mthe ‘right’ matrix in the chain complex; that is, the matrix that one takes the kernel of when computing homology.
Nthe ‘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
Mthe ‘right’ matrix in the chain complex; that is, the matrix that one takes the kernel of when computing homology.
Nthe ‘left’ matrix in the chain complex; that is, the matrix that one takes the image of when computing homology.
pcoeffspecifies 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
rkthe rank of the group as a Z_p-module. That is, if the group is n Z_p, then rk should be n.
pdescribes 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
iindicates the generator to replace.
jindicates the generator to combine with gi.
kindicates 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).
rightMulttrue 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
iindicates 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
iindicates the first of the two generators to switch.
jindicates 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
otherthe 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
compthe 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
otherthe 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
Xthe 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
otherthe 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
otherthe 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
outthe output stream to which to write.
termthe 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
cloneMethe 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
cloneMethe 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
cloneMethe 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
otherthe 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
compthe 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
otherthe 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
exponentthe 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
depthcontrols 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
otherthe word to compare against this.
cyclicif 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
indexthe 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
matrixa 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
cyclictrue 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
inputis 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
va 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
tagNamethe name of the opening tag for this element.
tagPropsthe properties associated with the opening tag.
parentReaderthe 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
tagNamethe name of the opening tag for this element.
tagPropsthe properties associated with the opening tag.
parentReaderthe 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
subTagNamethe name of the subelement opening tag.
subTagPropsthe 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
generatorthe generator to be replaced.
expansionthe substitute expression that will replace every occurrence of the given generator.
cyclictrue 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
indexthe 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
indexthe 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
degreethe 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
degreethe 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
degreethe 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
degreethe 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
indexspecifies 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
outthe 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
outthe 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
outthe 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
outthe output stream to which to write.
shortwordindicates whether to use numbered or alphabetic generators, as described above.
utf8true 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
outthe 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
outthe 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
outthe 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
outthe 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
outthe 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
outthe 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
outthe 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
outthe 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
outthe stream to write to.
utf8if 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
outthe output stream to which to write.
utf8if 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
outthe 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
outthe 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
outthe 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).