Regina Calculation Engine
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
regina::AbelianGroup Class Reference

Represents a finitely generated abelian group. More...

#include <algebra/abeliangroup.h>

Inheritance diagram for regina::AbelianGroup:
regina::ShortOutput< AbelianGroup, true > regina::Output< AbelianGroup, supportsUtf8 >

Public Member Functions

 AbelianGroup ()
 Creates a new trivial group. More...
 
 AbelianGroup (const AbelianGroup &cloneMe)=default
 Creates a clone of the given group. More...
 
 AbelianGroup (const MatrixInt &M, const MatrixInt &N)
 Creates an abelian group as the homology of a chain complex. More...
 
 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 addRank (int extraRank=1)
 Increments the rank of the group by the given integer. More...
 
void addTorsionElement (const Integer &degree, unsigned mult=1)
 Adds the given torsion element to the group. More...
 
void addTorsionElement (unsigned long degree, unsigned mult=1)
 Adds the given torsion element to the group. More...
 
void addTorsionElements (const std::multiset< Integer > &torsion)
 
Adds the given set of torsion elements to this group. More...
 
void addGroup (const MatrixInt &presentation)
 Adds the abelian group defined by the given presentation to this group. More...
 
void addGroup (const AbelianGroup &group)
 Adds the given abelian group to this group. More...
 
unsigned rank () const
 Returns the rank of the group. More...
 
unsigned torsionRank (const Integer &degree) const
 Returns the rank in the group of the torsion term of given degree. More...
 
unsigned torsionRank (unsigned long degree) const
 Returns the rank in the group of the torsion term of given degree. More...
 
size_t countInvariantFactors () const
 Returns the number of invariant factors that describe the torsion elements of this group. More...
 
const IntegerinvariantFactor (size_t index) const
 Returns the given invariant factor describing the torsion elements of this group. More...
 
bool isTrivial () const
 Determines whether this is the trivial (zero) group. More...
 
bool isZ () const
 Determines whether this is the infinite cyclic group (Z). More...
 
bool isFree (unsigned r) const
 Determines whether this is the free abelian group of the given rank. More...
 
bool isZn (unsigned long n) const
 Determines whether this is the non-trivial cyclic group on the given number of elements. More...
 
bool operator== (const AbelianGroup &other) const
 Determines whether this and the given abelian group are isomorphic. More...
 
bool operator!= (const AbelianGroup &other) const
 Determines whether this and the given abelian group are non-isomorphic. More...
 
AbelianGroupoperator= (const AbelianGroup &cloneMe)=default
 Sets this to be a clone of the given group. More...
 
void writeXMLData (std::ostream &out) const
 
Writes a chunk of XML containing this abelian group. More...
 
void writeTextShort (std::ostream &out, bool utf8=false) const
 
Writes a short text representation of this object to the given output stream. More...
 
void writeTextLong (std::ostream &out) const
 
A default implementation for detailed output. More...
 
std::string str () const
 
Returns a short text representation of this object. More...
 
std::string utf8 () const
 Returns a short text representation of this object using unicode characters. More...
 
std::string detail () const
 Returns a detailed text representation of this object. More...
 

Protected Member Functions

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

Protected Attributes

unsigned rank_
 The rank of the group (the number of Z components). More...
 
std::multiset< IntegerinvariantFactors
 The invariant factors d0,...,dn as described in the AbelianGroup notes. More...
 

Detailed Description

Represents a finitely generated abelian group.

The torsion elements of the group are stored in terms of their invariant factors. For instance, Z_2+Z_3 will appear as Z_6, and Z_2+Z_2+Z_3 will appear as Z_2+Z_6.

In general the factors will appear as Z_d0+...+Z_dn, where the invariant factors di are all greater than 1 and satisfy d0|d1|...|dn. Note that this representation is unique.

Todo:
Optimise (long-term): Look at using sparse matrices for storage of SNF and the like.

Constructor & Destructor Documentation

◆ AbelianGroup() [1/4]

regina::AbelianGroup::AbelianGroup ( )
inline

Creates a new trivial group.

◆ AbelianGroup() [2/4]

regina::AbelianGroup::AbelianGroup ( const AbelianGroup cloneMe)
default

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

Member Function Documentation

◆ addGroup() [1/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.

◆ addGroup() [2/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.

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

◆ 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
This routine takes a python list as its argument.
Parameters
torsiona list containing the torsion elements to add, as described above.

◆ countInvariantFactors()

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.

◆ detail()

std::string regina::Output< AbelianGroup , supportsUtf8 >::detail ( ) const
inherited

Returns a detailed text representation of this object.

This text may span many lines, and should provide the user with all the information they could want. It should be human-readable, should not contain extremely long lines (which cause problems for users reading the output in a terminal), and should end with a final newline. There are no restrictions on the underlying character set.

Returns
a detailed text representation of this object.

◆ invariantFactor()

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.

◆ isFree()

bool regina::AbelianGroup::isFree ( unsigned  r) const
inline

Determines whether this is the free abelian group of the given rank.

Parameters
rthe rank of the free abelian group that we are testing for.
Returns
true if and only if this is the free abelian group of rank r.

◆ isTrivial()

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.

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

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

◆ operator!=()

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

AbelianGroup& regina::AbelianGroup::operator= ( const AbelianGroup cloneMe)
default

Sets this to be a clone of the given group.

Parameters
cloneMethe group to clone.

◆ operator==()

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.

◆ rank()

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

Returns the rank of the group.

This is the number of included copies of Z.

Equivalently, the rank is the maximum number of linearly independent elements, and it indicates the size of the largest free abelian subgroup. The rank effectively ignores all torsion elements.

Warning
SnapPy users should be aware that SnapPy defines rank differently. Specifically, SnapPy's AbelianGroup.rank() computation includes torsion factors also.
Returns
the number of included copies of Z.

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

◆ str()

std::string regina::Output< AbelianGroup , supportsUtf8 >::str ( ) const
inherited


Returns a short text representation of this object.

This text should be human-readable, should fit on a single line, and should not end with a newline. Where possible, it should use plain ASCII characters.

Python
In addition to str(), this is also used as the Python "stringification" function __str__().
Returns
a short text representation of this object.

◆ torsionRank() [1/2]

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/2]

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.

◆ utf8()

std::string regina::Output< AbelianGroup , supportsUtf8 >::utf8 ( ) const
inherited

Returns a short text representation of this object using unicode characters.

Like str(), this text should be human-readable, should fit on a single line, and should not end with a newline. In addition, it may use unicode characters to make the output more pleasant to read. This string will be encoded in UTF-8.

Returns
a short text representation of this object.

◆ writeTextLong()

void regina::ShortOutput< AbelianGroup , supportsUtf8 >::writeTextLong ( std::ostream &  out) const
inlineinherited


A default implementation for detailed output.

This routine simply calls T::writeTextShort() and appends a final newline.

Python
Not present.
Parameters
outthe output stream to which to write.

◆ writeTextShort()

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

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


Writes a chunk of XML containing this abelian group.

Python
Not present.
Parameters
outthe output stream to which the XML should be written.

Member Data Documentation

◆ invariantFactors

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

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

◆ rank_

unsigned regina::AbelianGroup::rank_
protected

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


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

Copyright © 1999-2021, 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).