regina::NAbelianGroup Class Reference
Algebraic Structures

Represents a finitely generated abelian group. More...

`#include <algebra/nabeliangroup.h>`

Inheritance diagram for regina::NAbelianGroup:

## Public Member Functions

| NAbelianGroup ()
| Creates a new trivial group. More...
| NAbelianGroup (const NAbelianGroup &cloneMe)
| Creates a clone of the given group. More...
| NAbelianGroup (const NMatrixInt &M, const NMatrixInt &N)
| Creates an abelian group as the homology of a chain complex. More...
| NAbelianGroup (const NMatrixInt &M, const NMatrixInt &N, const NLargeInteger &p)
| Creates an abelian group as the homology of a chain complex, using mod-p coefficients. More...
virtual | ~NAbelianGroup ()
| Destroys the group. More...
void | addRank (int extraRank=1)
| Increments the rank of the group by the given integer. More...
void | addTorsionElement (const NLargeInteger &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< NLargeInteger > &torsion)
| Adds the given set of torsion elements to this group. More...
void | addGroup (const NMatrixInt &presentation)
| Adds the abelian group defined by the given presentation to this group. More...
void | addGroup (const NAbelianGroup &group)
| Adds the given abelian group to this group. More...
unsigned | getRank () const
| Returns the rank of the group. More...
unsigned | getTorsionRank (const NLargeInteger &degree) const
| Returns the rank in the group of the torsion term of given degree. More...
unsigned | getTorsionRank (unsigned long degree) const
| Returns the rank in the group of the torsion term of given degree. More...
unsigned long | getNumberOfInvariantFactors () const
| Returns the number of invariant factors that describe the torsion elements of this group. More...
const NLargeInteger & | getInvariantFactor (unsigned long 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 | isZn (unsigned long n) const
| Determines whether this is the non-trivial cyclic group on the given number of elements. More...
bool | operator== (const NAbelianGroup &other) const
| Determines whether this and the given abelian group are isomorphic. More...
void | writeXMLData (std::ostream &out) const
| Writes a chunk of XML containing this abelian group. More...
virtual void | writeTextShort (std::ostream &out) const
| The text representation will be of the form `3 Z + 4 Z_2 + Z_120`. More...
Public Member Functions inherited from regina::ShareableObject
| ShareableObject ()
| Default constructor that does nothing. More...
virtual | ~ShareableObject ()
| Default destructor that does nothing. More...
virtual void | writeTextLong (std::ostream &out) const
| Writes this object in long text format to the given output stream. More...
std::string | str () const
| Returns the output from writeTextShort() as a string. More...
std::string | toString () const
| A deprecated alias for str(), which returns the output from writeTextShort() as a string. More...
std::string | detail () const
| Returns the output from writeTextLong() as a string. More...
std::string | toStringLong () const
| A deprecated alias for detail(), which returns the output from writeTextLong() as a string. More...

## Protected Member Functions

void | replaceTorsion (const NMatrixInt &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 Member Functions inherited from regina::boost::noncopyable
| noncopyable ()
| A constructor which does nothing. More...
| ~noncopyable ()
| A destructor which does nothing. More...

## Protected Attributes

unsigned | rank
| The rank of the group (the number of Z components). More...
std::multiset< NLargeInteger > | invariantFactors
| The invariant factors d0,...,dn as described in the NAbelianGroup 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.

Test:
  Included in the test suite.

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

## Constructor & Destructor Documentation

regina::NAbelianGroup::NAbelianGroup | ( |  | ) |

inline

Creates a new trivial group.

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

inline

Creates a clone of the given group.

Parameters

  cloneMe | the group to clone.

regina::NAbelianGroup::NAbelianGroup | ( | const NMatrixInt & | M,
|  | const NMatrixInt & | N
| ) |  |

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

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

Parameters

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

Author
  Ryan Budney

regina::NAbelianGroup::NAbelianGroup | ( | const NMatrixInt & | M,
|  | const NMatrixInt & | N,
|  | const NLargeInteger & | p
| ) |  |

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

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

Parameters

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

Author
  Ryan Budney

regina::NAbelianGroup::~NAbelianGroup | ( |  | ) |

inline virtual

Destroys the group.

## Member Function Documentation

void regina::NAbelianGroup::addGroup | ( | const NMatrixInt & | 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.

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

Adds the given abelian group to this group.

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

Parameters

  group | the group to add to this one.

void regina::NAbelianGroup::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.

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

Adds the given torsion element to the group.

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

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

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

Parameters

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

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

inline

Adds the given torsion element to the group.

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

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

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

Parameters

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

void regina::NAbelianGroup::addTorsionElements | ( | const std::multiset< NLargeInteger > & | 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

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

const NLargeInteger& regina::NAbelianGroup::getInvariantFactor | ( | unsigned long | index | ) | const

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

See the NAbelianGroup 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 getNumberOfInvariantFactors()-1 inclusive.

Returns
  the requested invariant factor.

unsigned long regina::NAbelianGroup::getNumberOfInvariantFactors | ( |  | ) | const

inline

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

See the NAbelianGroup class notes for further details.

Returns
  the number of invariant factors.

unsigned regina::NAbelianGroup::getRank | ( |  | ) | const

inline

Returns the rank of the group.

This is the number of included copies of Z.

Returns
  the rank of the group.

unsigned regina::NAbelianGroup::getTorsionRank | ( | const NLargeInteger & | 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.

unsigned regina::NAbelianGroup::getTorsionRank | ( | 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.

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

inline

Determines whether this is the trivial (zero) group.

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

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

inline

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

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

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

bool regina::NAbelianGroup::operator== | ( | const NAbelianGroup & | 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.

void regina::NAbelianGroup::replaceTorsion | ( | const NMatrixInt & | matrix | ) |

protected

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

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

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

Parameters

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

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

virtual

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 NAbelianGroup notes.

Implements regina::ShareableObject.

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

Writes a chunk of XML containing this abelian group.

Python:
  Not present.

Parameters

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

## Member Data Documentation

std::multiset<NLargeInteger> regina::NAbelianGroup::invariantFactors

protected

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

unsigned regina::NAbelianGroup::rank

protected

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

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

- algebra/nabeliangroup.h

Copyright © 1999-2013, 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@debian.org).