Represents a finitely generated abelian group. More...

#include <algebra/abeliangroup.h>

Inheritance diagram for regina::AbelianGroup:

Public Member Functions
	AbelianGroup ()
	Creates a new trivial group. More...

	AbelianGroup (const AbelianGroup &)=default
	Creates a clone of the given group. More...

	AbelianGroup (AbelianGroup &&) noexcept=default
	Moves the contents of the given group to this new group. More...

	AbelianGroup (unsigned rank)
	Creates a free abelian group of the given rank. More...

template<typename T >
	AbelianGroup (unsigned rank, std::initializer_list< T > invFac)
	Creates a new group with the given rank and invariant factors. More...

template<typename Container >
	AbelianGroup (unsigned rank, const Container &invFac)
	Creates a new group with the given rank and invariant factors. More...

	AbelianGroup (MatrixInt presentation)
	Creates the abelian group defined by the given presentation matrix. More...

	AbelianGroup (MatrixInt M, MatrixInt N)
	Creates an abelian group as the homology of a chain complex. More...

	AbelianGroup (MatrixInt M, 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	addTorsion (Integer degree)
	Adds the given torsion element to the group. More...

void	addTorsionElement (const Integer &degree, unsigned mult=1)
	Deprecated routine that adds the given torsion element to the group. More...

void	addTorsionElement (unsigned long degree, unsigned mult=1)
	Deprecated routine that adds the given torsion element to the group. More...

void	addTorsionElements (const std::multiset< Integer > &torsion)
	Deprecated routine that adds the given set of torsion elements to this group. More...

void	addGroup (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 Integer &	invariantFactor (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 have identical presentations (which means they are isomorphic). More...

bool	operator!= (const AbelianGroup &other) const
	Determines whether this and the given abelian group have different presentations (which means they are non-isomorphic). More...

AbelianGroup &	operator= (const AbelianGroup &)=default
	Sets this to be a clone of the given group. More...

AbelianGroup &	operator= (AbelianGroup &&) noexcept=default
	Moves the contents of the given group to this group. More...

void	swap (AbelianGroup &other) noexcept
	Swaps the contents of this and the given abelian group. More...

void	tightEncode (std::ostream &out) const
	Writes the tight encoding of this abelian group to the given output stream. More...

std::string	tightEncoding () const
	Returns the tight encoding of this abelian 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 Attributes
unsigned	rank_ { 0 }
	The rank of the group (the number of Z components). More...

std::vector< Integer >	revInvFactors_
	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.

This class implements C++ move semantics and adheres to the C++ Swappable requirement. It is designed to avoid deep copies wherever possible, even when passing or returning objects by value.

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

Constructor & Destructor Documentation

◆ AbelianGroup() [1/9]

regina::AbelianGroup::AbelianGroup ( )

inline

Creates a new trivial group.

◆ AbelianGroup() [2/9]

regina::AbelianGroup::AbelianGroup ( const AbelianGroup & )

default

Creates a clone of the given group.

◆ AbelianGroup() [3/9]

regina::AbelianGroup::AbelianGroup ( AbelianGroup && )

defaultnoexcept

Moves the contents of the given group to this new group.

This is a fast (constant time) operation.

The group that was passed will no longer be usable.

◆ AbelianGroup() [4/9]

regina::AbelianGroup::AbelianGroup ( unsigned rank )

inline

Creates a free abelian group of the given rank.

Parameters

rank	the rank of the new group.

◆ AbelianGroup() [5/9]

template<typename T >

regina::AbelianGroup::AbelianGroup	(	unsigned	rank,
		std::initializer_list< T >	invFac
	)

inline

Creates a new group with the given rank and invariant factors.

Exceptions

The	invariant factors were not all greater than 1, and/or they did not satisfy the divisibily requirement (where each invariant factor must divide the one after it).

Python: Not available, but there is a constructor that takes the invariant factors as a Python list.

Template Parameters

T	an integer type, which may be a native C++ integer type or one of Regina's own integer types.

Parameters

rank	the rank of the new group (i.e., the number of copies of Z).
invFac	the list of invariant factors d0, d1, ..., as described in the class notes, where each invariant factor is greater than 1 and divides the invariant factor after it.

◆ AbelianGroup() [6/9]

template<typename Container >

regina::AbelianGroup::AbelianGroup	(	unsigned	rank,
		const Container &	invFac
	)

inline

Creates a new group with the given rank and invariant factors.

Exceptions

The	invariant factors were not all greater than 1, and/or they did not satisfy the divisibily requirement (where each invariant factor must divide the one after it).

Template Parameters

Container a container or view that supports reverse iteration via rbegin(), rend(), that has an empty() function, and whose elements may be of a native C++ integer type or one of Regina's own integer types. A suitable example might be std::vector<int>.

Parameters

rank	the rank of the new group (i.e., the number of copies of Z).
invFac	the list of invariant factors d0, d1, ..., as described in the class notes, where each invariant factor is greater than 1 and divides the invariant factor after it.

◆ AbelianGroup() [7/9]

regina::AbelianGroup::AbelianGroup ( MatrixInt presentation )

Creates the abelian group defined by the given presentation matrix.

Each column of the matrix represents a generator, and each row of the matrix represents a relation.

Parameters

presentation a presentation matrix for the new group.

◆ AbelianGroup() [8/9]

regina::AbelianGroup::AbelianGroup	(	MatrixInt	M,
		MatrixInt	N
	)

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

The abelian group is the kernel of M modulo the image of N.

The matrices should be thought of as acting on column vectors: this means that the product B*A applies the linear transformation A, then the linear transformation B. This is consistent (for example) with the convention that Regina uses for for multiplying permutations.

Precondition: M.columns() = N.rows(). This condition will be tested, and an exception will be thrown if it does not hold.; The product M*N = 0. This condition will not be tested (for efficiency reasons); this is left to the user/programmer to ensure.

Exceptions

InvalidArgument The number of columns in M does not match the number of rows in N.

Parameters

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

◆ AbelianGroup() [9/9]

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

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

The abelian group is the kernel of M modulo the image of N.

The matrices should be thought of as acting on column vectors: this means that the product B*A applies the linear transformation A, then the linear transformation B. This is consistent (for example) with the convention that Regina uses for for multiplying permutations.

Precondition: M.columns() = N.rows(). This condition will be tested, and an exception will be thrown if it does not hold.; The product M*N = 0. This condition will not be tested (for efficiency reasons); this is left to the user/programmer to ensure.

Exceptions

InvalidArgument The number of columns in M does not match the number of rows in N.

Parameters

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

Author: Ryan Budney

Member Function Documentation

◆ addGroup() [1/2]

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

Adds the given abelian group to this group.

Parameters

group the group to add to this one.

◆ addGroup() [2/2]

void regina::AbelianGroup::addGroup ( MatrixInt presentation )

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

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

Parameters

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

◆ addRank()

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

inline

Increments the rank of the group by the given integer.

This integer may be positive, negative or zero.

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

Parameters

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

◆ addTorsion()

void regina::AbelianGroup::addTorsion ( Integer degree )

Adds the given torsion element to the group.

As of Regina 7.0, this routine is much faster than it used to be. In particular, if you have many torsion elements to add, it is now efficient just to call addTorsion() for each new torsion element, one at a time.

In this routine we add a single copy of Z_d, where d is the given degree.

Parameters

degree the degree of the new torsion element; this must be strictly positive.

◆ addTorsionElement() [1/2]

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

inline

Deprecated routine that adds the given torsion element to the group.

As of Regina 7.0, this routine is much faster than it used to be. In particular, if you have many torsion elements to add, it is now efficient just to call addTorsion() for each new torsion element, one at a time.

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

Deprecated:: Use addTorsion() instead, multiple times if necessary (which is exactly how this routine is implemented).

Precondition: The given degree is strictly positive, and the given multiplicity is at least 1.

Parameters

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

◆ addTorsionElement() [2/2]

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

inline

Deprecated routine that adds the given torsion element to the group.

As of Regina 7.0, this routine is much faster than it used to be. In particular, if you have many torsion elements to add, it is now efficient just to call addTorsion() for each new torsion element, one at a time.

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

Deprecated:: Use addTorsion() instead, multiple times if necessary (which is exactly how this routine is implemented).

Precondition: The given degree is strictly positive, and the given multiplicity is at least 1.

Parameters

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

◆ addTorsionElements()

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

Deprecated routine that adds the given set of torsion elements to this group.

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.

Deprecated:: This routine uses an old implementation, and it is now much faster just to add each torsion element one at a time using addTorsion().

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

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

Parameters

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

template<class T , bool supportsUtf8 = false>

std::string regina::Output< T, 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

inline

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

See the AbelianGroup class notes for further details.

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

Parameters

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

Returns: the requested invariant factor.

◆ isFree()

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

inline

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

Parameters

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

n	the 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 have different presentations (which means they are non-isomorphic).

Since the AbelianGroup class stores only the invariants required to identify the isomorphism type, two groups will compare as equal if and only if they are isomorphic. This is in contrast to the comparisons for GroupPresentation (which tests for identical generators and relations), or for MarkedAbelianGroup (which tests for identical chain complex presentations).

Parameters

other the group with which this should be compared.

Returns: true if and only if the two groups have different presentations (i.e., they are non-isomorphic).

◆ operator=() [1/2]

AbelianGroup & regina::AbelianGroup::operator= ( AbelianGroup && )

defaultnoexcept

Moves the contents of the given group to this group.

This is a fast (constant time) operation.

The group that was passed will no longer be usable.

Returns: a reference to this group.

◆ operator=() [2/2]

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

default

Sets this to be a clone of the given group.

Returns: a reference to this group.

◆ operator==()

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

inline

Determines whether this and the given abelian group have identical presentations (which means they are isomorphic).

Since the AbelianGroup class stores only the invariants required to identify the isomorphism type, two groups will compare as equal if and only if they are isomorphic. This is in contrast to the comparisons for GroupPresentation (which tests for identical generators and relations), or for MarkedAbelianGroup (which tests for identical chain complex presentations).

Parameters

other the group with which this should be compared.

Returns: true if and only if the two groups have identical presentations (i.e., they 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.

◆ str()

template<class T , bool supportsUtf8 = false>

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

inherited

Returns a short text representation of this object.

This text should be human-readable, should use plain ASCII characters where possible, and should not contain any newlines.

Within these limits, this short text ouptut should be as information-rich as possible, since in most cases this forms the basis for the Python str() and repr() functions.

Python: The Python "stringification" function str() will use precisely this function, and for most classes the Python repr() function will incorporate this into its output.

Returns: a short text representation of this object.

◆ swap()

void regina::AbelianGroup::swap ( AbelianGroup & other )

inlinenoexcept

Swaps the contents of this and the given abelian group.

Parameters

other the group whose contents should be swapped with this.

◆ tightEncode()

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

inline

Writes the tight encoding of this abelian group to the given output stream.

See the page on tight encodings for details.

Python: Not present; use tightEncoding() instead.

Parameters

out	the output stream to which the encoded string will be written.

◆ tightEncoding()

std::string regina::AbelianGroup::tightEncoding ( ) const

inline

Returns the tight encoding of this abelian group.

See the page on tight encodings for details.

Returns: the resulting encoded string.

◆ 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

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

degree the degree of the torsion term to query.

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

◆ utf8()

template<class T , bool supportsUtf8 = false>

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

inherited

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

Like str(), this text should be human-readable, should not contain any newlines, and (within these constraints) should be as information-rich as is reasonable.

Unlike str(), this function may use unicode characters to make the output more pleasant to read. The string that is returned 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; instead you can call detail() from the subclass T, which returns this output as a string.

Parameters

out	the 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; use str() or utf8() instead.

Parameters

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

◆ writeXMLData()

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

Writes a chunk of XML containing this abelian group.

Python: The argument out should be an open Python file object.

Parameters

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

Member Data Documentation

◆ rank_

unsigned regina::AbelianGroup::rank_ { 0 }

protected

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

◆ revInvFactors_

std::vector<Integer> regina::AbelianGroup::revInvFactors_

protected

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

These are stored in reverse order, since addTorsion() always extends the vector on the d0 end. Note that we cannot use std::deque (which does support pushing to the front), since older gcc versions do not have a noexcept std::deque move constructor.

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

algebra/abeliangroup.h

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ AbelianGroup() [1/9]

◆ AbelianGroup() [2/9]

◆ AbelianGroup() [3/9]

◆ AbelianGroup() [4/9]

◆ AbelianGroup() [5/9]

◆ AbelianGroup() [6/9]

◆ AbelianGroup() [7/9]

◆ AbelianGroup() [8/9]

◆ AbelianGroup() [9/9]

Member Function Documentation

◆ addGroup() [1/2]

◆ addGroup() [2/2]

◆ addRank()

◆ addTorsion()

◆ addTorsionElement() [1/2]

◆ addTorsionElement() [2/2]

◆ addTorsionElements()

◆ countInvariantFactors()

◆ detail()

◆ invariantFactor()

◆ isFree()

◆ isTrivial()

◆ isZ()

◆ isZn()

◆ operator!=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ rank()

◆ str()

◆ swap()

◆ tightEncode()

◆ tightEncoding()

◆ torsionRank() [1/2]

◆ torsionRank() [2/2]

◆ utf8()

◆ writeTextLong()

◆ writeTextShort()

◆ writeXMLData()

Member Data Documentation

◆ rank_

◆ revInvFactors_