Represents a finitely generated abelian group given by a chain complex. More...

#include <algebra/markedabeliangroup.h>

Inheritance diagram for regina::MarkedAbelianGroup:

Public Member Functions
	MarkedAbelianGroup (MatrixInt M, MatrixInt N)
	Creates a marked abelian group from a chain complex. More...

	MarkedAbelianGroup (MatrixInt M, MatrixInt N, Integer pcoeff)
	Creates a marked abelian group from a chain complex with coefficients in Z_p. More...

	MarkedAbelianGroup (unsigned long rank, 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...

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

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

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

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

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

const MatrixInt &	m () const
	Returns the "right" matrix that was used to define the chain complex. More...

const MatrixInt &	M () const
	Deprecated alias for m(). More...

const MatrixInt &	n () const
	Returns the "left" matrix that was used to define the chain complex. More...

const MatrixInt &	N () const
	Deprecated alias for n(). More...

const Integer &	coefficients () const
	Returns the coefficients used for the computation of homology. More...

unsigned long	rank () const
	Returns the rank of the group. More...

unsigned long	torsionRank (const Integer &degree) const
	Returns the rank in the group of the torsion term of given degree. More...

unsigned long	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...

AbelianGroup	unmarked () const
	Returns just the underlying abelian group, without any of the chain complex information. More...

unsigned long	ccRank () const
	Returns the rank of the chain complex supporting the homology computation. More...

unsigned long	rankCC () const
	Deprecated alias for ccRank(). More...

unsigned long	snfRank () const
	Returns the minimum number of generators for this group. More...

unsigned long	minNumberOfGenerators () const
	Deprecated alias for snfRank(). 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	isIsomorphicTo (const MarkedAbelianGroup &other) const
	Determines whether this and the given abelian group are isomorphic. More...

bool	operator== (const MarkedAbelianGroup &other) const
	Determines whether this and the given group were formed from identical chain complex constructions. More...

bool	operator!= (const MarkedAbelianGroup &other) const
	Determines whether this and the given group were formed from different chain complex constructions. More...

bool	equalTo (const MarkedAbelianGroup &other) const
	Deprecated routine that determines whether this and the given group were formed from identical chain complex constructions. More...

Vector< Integer >	freeRep (unsigned long index) const
	Returns the requested free generator of this group, represented in the original chain complex defining the group. More...

Vector< Integer >	torsionRep (unsigned long index) const
	Returns the requested generator of the torsion subgroup, represented in the original chain complex defining the group. More...

Vector< Integer >	ccRep (const Vector< Integer > &snf) const
	A combination of freeRep and torsionRep, this routine takes a group element expressed in SNF coordinates and returns a corresponding vector in the original chain complex. More...

Vector< Integer >	ccRep (unsigned long snfGen) const
	A combination of freeRep() and torsionRep() that expresses a group element as a vector in the original chain complex. More...

Vector< Integer >	snfRep (const Vector< Integer > &cycle) const
	Expresses the given cycle as a combination of free and torsion generators. More...

Vector< Integer >	cycleProjection (const Vector< Integer > &ccelt) const
	Projects an element of the chain complex to the subspace of cycles. More...

Vector< Integer >	cycleProjection (unsigned long ccindx) const
	Projects a standard basis vector of the chain complex to the subspace of cycles. More...

bool	isCycle (const Vector< Integer > &chain) const
	Determines whether the given vector represents a cycle in the chain complex. More...

Vector< Integer >	boundaryOf (const Vector< Integer > &chain) const
	Computes the differential of the given vector in the chain complex whose kernel is the cycles. More...

Vector< Integer >	boundaryMap (const Vector< Integer > &chain) const
	Deprecated alias for boundaryOf(). More...

bool	isBoundary (const Vector< Integer > &chain) const
	Determines whether the given vector represents a boundary in the chain complex. More...

Vector< Integer >	asBoundary (const Vector< Integer > &bdry) const
	Expresses the given vector as a boundary in the chain complex. More...

Vector< Integer >	writeAsBoundary (const Vector< Integer > &bdry) const
	Deprecated alias for asBoundary(). More...

unsigned long	cycleRank () const
	Returns the number of generators of the kernel of M, where M is the "right" matrix used to define the chain complex. More...

unsigned long	minNumberCycleGens () const
	Deprecated alias for cycleRank(). More...

Vector< Integer >	cycleGen (unsigned long index) const
	Returns the requested generator of the cycles, i.e., the kernel of the "right" matrix M in the chain complex. More...

MarkedAbelianGroup	torsionSubgroup () const
	Returns the torsion subgroup of this group. More...

HomMarkedAbelianGroup	torsionInclusion () const
	Returns a map representing the inclusion of the torsion subgroup into this 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...

Friends
class	HomMarkedAbelianGroup

Detailed Description

Represents a finitely generated abelian group given by a chain complex.

This class is initialized with a chain complex. The chain complex is given in terms of two integer matrices M and N such that M*N=0. These matrices should be thought of as acting on column vectors: this means for example that the product B*A applies the linear transformation A, then the linear transformation B. This is consistent with the convention that Regina uses for for multiplying permutations.

The abelian group that this class computes is the kernel of M modulo the image of N. In other words, we compute the homology of the chain complex Z^a –N--> Z^b –M--> Z^c, where a = N.columns(), b = M.columns() = N.rows(), and c = M.rows(). An additional constructor allows you to take the homology with coefficients in an arbitrary cyclic group.

Like the simpler class AbelianGroup, this group will be isomorphic to some Z_{d0} + ... + Z_{dk} + Z^r, where:

r 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 class allows you to retrieve the invariant factors, the rank, and the corresponding vectors in the kernel of M. Moreover, given a vector in the kernel of M, it decribes the homology class of the vector (the free part, and its position in the invariant factors).

The purpose of this class is to not just represent homology groups, but also to support coordinates on the group allowing for the construction of homomorphisms, and keeping track of subgroups.

This routine makes frequent use of two coordinate systems:

Chain complex coordinates describe vectors of length b (using the notation above); that is, elements of the domain of M, or equivalently the codomain of N.
SNF (or Smith normal form) coordinates describe elements of this abelian group in terms of the torsion and free generators. A vector in SNF coordinates has length (k + r), again using the notation above, where the first k elements store coefficients for the generators of the torsion components Z_{d1}, ..., Z_{dk}, and the remaining r elements store coefficients for the r free generators. You can see how the torsion and free generators appear in chain complex coordinates by calling torsionRep() or freeRep() respectively.

Be aware that the choice of torsion and free generators is typically not unique, and this will affect the results of many member functions of this class. These choices are subject to change between different versions of Regina; in particular, they depend upon the particular algorithm used for computing Smith normal forms.

Some routines in this class refer to the internal presentation matrix. This is a proper presentation matrix for the abelian group; if you are looking at the implementation details, this refers to the matrix pres, created by taking the product MRi_ * N and then removing the first rankM_ rows.

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.

Author: Ryan Budney and B.B.

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

Constructor & Destructor Documentation

◆ MarkedAbelianGroup() [1/5]

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

Creates a marked abelian group from a chain complex.

This constructor assumes you are interested in homology with integer coefficents.

The abelian group is the kernel of M modulo the image of N. See the class notes for further details.

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.

◆ MarkedAbelianGroup() [2/5]

regina::MarkedAbelianGroup::MarkedAbelianGroup	(	MatrixInt	M,
		MatrixInt	N,
		Integer	pcoeff
	)

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

The abelian group is the kernel of M modulo the image of N. See the class notes for further details.

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.
pcoeff	specifies the coefficient ring, Z_pcoeff. This must be non-negative; a value of 0 indicates that you are using integer coefficients (in which case it is more efficient to use the constructor that just takes two matrices).

◆ MarkedAbelianGroup() [3/5]

regina::MarkedAbelianGroup::MarkedAbelianGroup	(	unsigned long	rank,
		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.

This group is isomorphic to n Z_p. Moreover, if constructed using the matrices-with-coefficients constructor, M would be zero and N would be diagonal and square with p down the diagonal.

Parameters

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

◆ MarkedAbelianGroup() [4/5]

regina::MarkedAbelianGroup::MarkedAbelianGroup ( const MarkedAbelianGroup & )

default

Creates a clone of the given group.

◆ MarkedAbelianGroup() [5/5]

regina::MarkedAbelianGroup::MarkedAbelianGroup ( MarkedAbelianGroup && )

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.

Member Function Documentation

◆ asBoundary()

Vector< Integer > regina::MarkedAbelianGroup::asBoundary ( const Vector< Integer > & bdry ) const

Expresses the given vector as a boundary in the chain complex.

Warning: If you are using mod p coefficients and if your element projects to a non-trivial element of TOR, then N*v != bdry as elements of TOR are not in the image of N. In this case, (bdry - N*v) represents the projection to TOR.; The return value is not unique. The specific choice of vector may change between different versions of Regina.

Exceptions

InvalidArgument The given vector is not a boundary.

Parameters

bdry	a boundary vector, given in chain complex coordinates.

Returns: a vector v such that N*v=bdry.

◆ boundaryMap()

Vector< Integer > regina::MarkedAbelianGroup::boundaryMap ( const Vector< Integer > & chain ) const

inline

Deprecated alias for boundaryOf().

Deprecated:: This routine has been renamed to boundaryOf().

Exceptions

InvalidArgument The given vector is not in chain complex coordinates; that is, its length is not M.columns().

Parameters

chain any vector in chain complex coordinates.

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

◆ boundaryOf()

Vector< Integer > regina::MarkedAbelianGroup::boundaryOf ( const Vector< Integer > & chain ) const

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

In other words, this routine returns M*chain, where M is the "right" matrix passed to the class constructor.

Exceptions

InvalidArgument The given vector is not in chain complex coordinates; that is, its length is not M.columns().

Parameters

chain any vector in chain complex coordinates.

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

◆ ccRank()

unsigned long regina::MarkedAbelianGroup::ccRank ( ) const

inline

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

This is the dimension of a vector in chain complex coordinates. In the class notes, this is given by M.columns() and N.rows(), where M and N are the matrices used to define the chain complex.

Returns: the rank of the chain complex.

◆ ccRep() [1/2]

Vector< Integer > regina::MarkedAbelianGroup::ccRep ( const Vector< Integer > & snf ) const

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

This routine is, in some sense, an inverse to snfRep().

Warning: The return value is not unique. The specific choice of vector may change between different versions of Regina.

Exceptions

InvalidArgument The size of the given vector was not precisely snfRank().

Parameters

snf	any vector in SNF coordinates.

Returns: a corresponding vector in chain complex coordinates.

◆ ccRep() [2/2]

Vector< Integer > regina::MarkedAbelianGroup::ccRep ( unsigned long snfGen ) const

A combination of freeRep() and torsionRep() that expresses a group element as a vector in the original chain complex.

This is similar to the variant of ccRep() that takes a vector as input, but it assumes that your input is a standard basis vector from SNF coordinates. Calling ccRep(snfGen) is equivalent to passing the (snfGen)th unit vector to ccRep().

Warning: The return value is not unique. The specific choice of vector may change between different versions of Regina.

Exceptions

InvalidArgument The given index was greater than or equal to the number of generators in SNF coordinates (i.e., greater than or equal to snfRank()).

Parameters

snfGen specifies which standard basis vector to use from SNF coordinates; this must be between 0 and snfRank()-1 inclusive.

Returns: a corresponding vector in chain complex coordinates.

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

◆ countInvariantFactors()

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.

◆ cycleGen()

Vector< Integer > regina::MarkedAbelianGroup::cycleGen ( unsigned long index ) const

Returns the requested generator of the cycles, i.e., the kernel of the "right" matrix M in the chain complex.

Warning: The return value is not unique. The specific choice of vector may change between different versions of Regina.

Exceptions

InvalidArgument The argument index was out of range (i.e., greater than or equal to cycleRank()).

Parameters

index indicates which generator to return; this must be between 0 and cycleRank()-1 inclusive.

Returns: the (index)th generator of the cycles, expressed in chain complex coordinates.

◆ cycleProjection() [1/2]

Vector< Integer > regina::MarkedAbelianGroup::cycleProjection ( const Vector< Integer > & ccelt ) const

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

Warning: The return value is not unique. The specific choice of vector may change between different versions of Regina.

Exceptions

InvalidArgument The length of the given vector was not the dimension of the chain complex (i.e., the number of chain complex coordinates).

Parameters

ccelt any vector in chain complex coordinates.

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

◆ cycleProjection() [2/2]

Vector< Integer > regina::MarkedAbelianGroup::cycleProjection ( unsigned long ccindx ) const

Projects a standard basis vector of the chain complex to the subspace of cycles.

Warning: The return value is not unique. The specific choice of vector may change between different versions of Regina.

Exceptions

InvalidArgument The index ccindx was greater than or equal to the dimension of the chain complex (i.e., ccRank()).

Parameters

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

Returns: the resulting projection, in the chain complex coordinates.

◆ cycleRank()

unsigned long regina::MarkedAbelianGroup::cycleRank ( ) const

inline

Returns the number of generators of the kernel of M, where M is the "right" matrix used to define the chain complex.

Returns: the number of generators of ker(M).

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

◆ equalTo()

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

inline

Deprecated routine that determines whether this and the given group were formed from identical chain complex constructions.

Deprecated:: This routine is now offered as the equality comparison operator (==).

Parameters

other the group with which this should be compared.

Returns: true if and only if the this and the given group have identical chain complex definitions.

◆ freeRep()

Vector< Integer > regina::MarkedAbelianGroup::freeRep ( unsigned long index ) const

Returns the requested free generator of this group, represented in the original chain complex defining the group.

The generator will be presented in chain complex coordinates.

Warning: The return value is not unique. The specific choice of vector may change between different versions of Regina.

Exceptions

InvalidArgument The argument index is out of range (i.e., greater than or equal to rank()).

Parameters

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

Returns: the (index)th free generator, presented in chain complex coordinates.

◆ invariantFactor()

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

inline

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

See the MarkedAbelianGroup class notes for further details.

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

Parameters

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

Returns: the requested invariant factor.

◆ isBoundary()

bool regina::MarkedAbelianGroup::isBoundary ( const Vector< Integer > & chain ) const

Determines whether the given vector represents a boundary in the chain complex.

Parameters

chain any vector in chain complex coordinates.

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

◆ isCycle()

bool regina::MarkedAbelianGroup::isCycle ( const Vector< Integer > & chain ) const

Determines whether the given vector represents a cycle in the chain complex.

Parameters

chain any vector in chain complex coordinates.

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

◆ isIsomorphicTo()

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

inline

Determines whether this and the given abelian group are isomorphic.

Parameters

other the group with which this should be compared.

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

◆ isTrivial()

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.

◆ isZ()

bool regina::MarkedAbelianGroup::isZ ( ) const

inline

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

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

◆ m()

const MatrixInt & regina::MarkedAbelianGroup::m ( ) const

inline

Returns the "right" matrix that was used to define the chain complex.

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

This is 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.

◆ M()

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

inline

Deprecated alias for m().

Deprecated:: This routine has been renamed to lower-case m().

Returns: a reference to the defining matrix M.

◆ minNumberCycleGens()

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

inline

Deprecated alias for cycleRank().

Deprecated:: This routine has been renamed to cycleRank().

Returns: the number of generators of ker(M).

◆ minNumberOfGenerators()

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

inline

Deprecated alias for snfRank().

Deprecated:: This routine has been renamed to snfRank().

Returns: the minimum number of generators.

◆ n()

const MatrixInt & regina::MarkedAbelianGroup::n ( ) const

inline

Returns the "left" matrix that was used to define the chain complex.

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

This is 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.

◆ N()

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

inline

Deprecated alias for n().

Deprecated:: This routine has been renamed to lower-case n().

Returns: a reference to the defining matrix N.

◆ operator!=()

bool regina::MarkedAbelianGroup::operator!= ( const MarkedAbelianGroup & other ) const

inline

Determines whether this and the given group were formed from different chain complex constructions.

This is not an isomorphism test. For this comparison to return false (i.e., for the chain complex constructions to be considered identical), both groups must have been constructed from identical matrices M and N, using homology with the same coefficients.

Parameters

other the group with which this should be compared.

Returns: true if and only if the this and the given group do not have identical chain complex definitions.

◆ operator=() [1/2]

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

default

Sets this to be a clone of the given group.

Returns: a reference to this group.

◆ operator=() [2/2]

MarkedAbelianGroup & regina::MarkedAbelianGroup::operator= ( MarkedAbelianGroup && )

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

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

inline

Determines whether this and the given group were formed from identical chain complex constructions.

This is not an isomorphism test. For this comparison to return true, both groups must have been constructed from identical matrices M and N, using homology with the same coefficients.

Parameters

other the group with which this should be compared.

Returns: true if and only if the this and the given group have identical chain complex definitions.

◆ rank()

unsigned long regina::MarkedAbelianGroup::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.

Returns: the rank of the group.

◆ rankCC()

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

inline

Deprecated alias for ccRank().

Deprecated:: This routine has been renamed to ccRank().

Returns: the rank of the chain complex.

◆ snfRank()

unsigned long regina::MarkedAbelianGroup::snfRank ( ) const

inline

Returns the minimum number of generators for this group.

This is the dimension of a vector in SNF coordinates. It will always be equal to rank() + countInvariantFactors().

Returns: the minimum number of generators.

◆ snfRep()

Vector< Integer > regina::MarkedAbelianGroup::snfRep ( const Vector< Integer > & cycle ) const

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

This routine takes a single argument cycle, which should be a cycle in chain complex coordinates. This routine then returns this cycle as a group element, expressed in SNF coordinates. See the class notes for a full explanation of what these concepts mean.

In the vector that is returned, the coordinates that hold coefficients for the torsion generators will be non-negative integers modulo the corresponding invariant factors d1, ..., dk.

Specifically, using the notation from the class notes, suppose cycle belongs to ker(M) and snfRep(cycle) returns the vector (b1, ..., bk, a1, ..., ar). Suppose furthermore that the free generators returned by freeRep(0..(r-1)) are f1, ..., fr respectively, and that the torsion generators returned by torsionRep(0..(k-1)) are t1, ..., tk respectively. Then cycle = b1.t1 + ... + bk.tk + a1.f1 + ... + ar.fr modulo img(N).

Warning: The return value is not unique. The specific choice of vector may change between different versions of Regina.

Exceptions

InvalidArgument The given vector was the wrong size, or is not a cycle (i.e., not in the kernel of M).

Parameters

cycle a cycle, presented in chain complex coordinates.

Returns: the group element corresponding to cycle, expressed in SNF coordinates.

◆ 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::MarkedAbelianGroup::swap ( MarkedAbelianGroup & other )

noexcept

Swaps the contents of this and the given group.

Parameters

other the group whose contents should be swapped with this.

◆ torsionInclusion()

HomMarkedAbelianGroup regina::MarkedAbelianGroup::torsionInclusion ( ) const

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

Returns: the inclusion map for the torsion subgroup.

◆ torsionRank() [1/2]

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

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

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

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

Precondition: The given degree is at least 2.

Parameters

degree the degree of the torsion term to query.

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

◆ torsionRank() [2/2]

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

inline

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

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

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

Precondition: The given degree is at least 2.

Parameters

degree the degree of the torsion term to query.

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

◆ torsionRep()

Vector< Integer > regina::MarkedAbelianGroup::torsionRep ( unsigned long index ) const

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

The generator will be presented in chain complex coordinates.

Warning: The return value is not unique. The specific choice of vector may change between different versions of Regina.

Exceptions

InvalidArgument The argument index is out of range (i.e., greater than or equal to countInvariantFactors()).

Parameters

index specifies which generator in the torsion subgroup; this must be between 0 and countInvariantFactors()-1 inclusive.

Returns: the (index)th torsion generator, presented in chain complex coordinates.

◆ torsionSubgroup()

MarkedAbelianGroup regina::MarkedAbelianGroup::torsionSubgroup ( ) const

Returns the torsion subgroup of this group.

Returns: the torsion subgroup.

◆ unmarked()

AbelianGroup regina::MarkedAbelianGroup::unmarked ( ) const

inline

Returns just the underlying abelian group, without any of the chain complex information.

Returns: the abelian group.

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

◆ writeAsBoundary()

Vector< Integer > regina::MarkedAbelianGroup::writeAsBoundary ( const Vector< Integer > & bdry ) const

Deprecated alias for asBoundary().

Deprecated:: This routine has been renamed to asBoundary().

Exceptions

InvalidArgument The given vector is not a boundary.

Parameters

bdry	a boundary vector, given in chain complex coordinates.

Returns: a vector v such that N*v=bdry.

◆ writeTextLong()

void regina::ShortOutput< MarkedAbelianGroup , 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::MarkedAbelianGroup::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 MarkedAbelianGroup notes.

Python: Not present; use str() or utf8() instead.

Parameters

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

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

algebra/markedabeliangroup.h

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ MarkedAbelianGroup() [1/5]

◆ MarkedAbelianGroup() [2/5]

◆ MarkedAbelianGroup() [3/5]

◆ MarkedAbelianGroup() [4/5]

◆ MarkedAbelianGroup() [5/5]

Member Function Documentation

◆ asBoundary()

◆ boundaryMap()

◆ boundaryOf()

◆ ccRank()

◆ ccRep() [1/2]

◆ ccRep() [2/2]

◆ coefficients()

◆ countInvariantFactors()

◆ cycleGen()

◆ cycleProjection() [1/2]

◆ cycleProjection() [2/2]

◆ cycleRank()

◆ detail()

◆ equalTo()

◆ freeRep()

◆ invariantFactor()

◆ isBoundary()

◆ isCycle()

◆ isIsomorphicTo()

◆ isTrivial()

◆ isZ()

◆ m()

◆ M()

◆ minNumberCycleGens()

◆ minNumberOfGenerators()

◆ n()

◆ N()

◆ operator!=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ rank()

◆ rankCC()

◆ snfRank()

◆ snfRep()

◆ str()

◆ swap()

◆ torsionInclusion()

◆ torsionRank() [1/2]

◆ torsionRank() [2/2]

◆ torsionRep()

◆ torsionSubgroup()

◆ unmarked()

◆ utf8()

◆ writeAsBoundary()

◆ writeTextLong()

◆ writeTextShort()