regina::NAbelianGroup Class Reference
[Algebraic Structures]

Represents a finitely generated abelian group. More...

#include <nabeliangroup.h>

Inheritance diagram for regina::NAbelianGroup:
regina::ShareableObject regina::boost::noncopyable

List of all members.

Public Member Functions

 NAbelianGroup ()
 Creates a new trivial group.
 NAbelianGroup (const NAbelianGroup &cloneMe)
 Creates a clone of the given group.
virtual ~NAbelianGroup ()
 Destroys the group.
void addRank (unsigned extraRank=1)
 Increments the rank of the group by the given non-negative integer.
void addTorsionElement (const NLargeInteger &degree, unsigned mult=1)
 Adds the given torsion element to the group.
void addTorsionElement (unsigned long degree, unsigned mult=1)
 Adds the given torsion element to the group.
void addTorsionElements (const std::multiset< NLargeInteger > &torsion)
 Adds the given set of torsion elements to this group.
void addGroup (const NMatrixInt &presentation)
 Adds the abelian group defined by the given presentation to this group.
void addGroup (const NAbelianGroup &group)
 Adds the given abelian group to this group.
unsigned getRank () const
 Returns the rank of the group.
unsigned getTorsionRank (const NLargeInteger &degree) const
 Returns the rank in the group of the torsion term of given degree.
unsigned getTorsionRank (unsigned long degree) const
 Returns the rank in the group of the torsion term of given degree.
unsigned long getNumberOfInvariantFactors () const
 Returns the number of invariant factors that describe the torsion elements of this group.
const NLargeIntegergetInvariantFactor (unsigned long index) const
 Returns the given invariant factor describing the torsion elements of this group.
bool isTrivial () const
 Determines whether this is the trivial (zero) group.
bool operator== (const NAbelianGroup &other) const
 Determines whether this and the given abelian group are isomorphic.
void writeXMLData (std::ostream &out) const
 Writes a chunk of XML containing this abelian group.
void writeToFile (NFile &out) const
 Writes this abelian group to the given old-style binary file.
virtual void writeTextShort (std::ostream &out) const
 The text representation will be of the form 3 Z + 4 Z_2 + Z_120.

Static Public Member Functions

static NAbelianGroupreadFromFile (NFile &in)
 Reads an abelian group from the given old-style binary file.

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.

Protected Attributes

unsigned rank
 The rank of the group (the number of Z components).
std::multiset< NLargeIntegerinvariantFactors
 The invariant factors d0,.

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:
Tested in the test suite, though not exhaustively.
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 (  )  [inline, virtual]

Destroys the group.


Member Function Documentation

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::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::addRank ( unsigned  extraRank = 1  )  [inline]

Increments the rank of the group by the given non-negative integer.

Parameters:
extraRank the extra rank to add; 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::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::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 ( 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.
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.
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::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.
static NAbelianGroup* regina::NAbelianGroup::readFromFile ( NFile in  )  [static]

Reads an abelian group from the given old-style binary file.

The group will be newly allocated, and responsibility for its destruction lies with the caller of this routine.

Deprecated:
For the preferred way of reading abelian groups from file, see class NXMLAbelianGroupReader instead.
Precondition:
The given file is currently opened for reading.
Python:
Not present.
Parameters:
in the file from which to read.
Returns:
a newly allocated group read from the given file, or 0 if problems arose.
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::writeToFile ( NFile out  )  const

Writes this abelian group to the given old-style binary file.

Deprecated:
For the preferred way to write data to file, see writeXMLData() instead.
Precondition:
The given file is currently opened for writing.
Python:
Not present.
Parameters:
out the file to which to write.
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

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:

Copyright © 1999-2009, Ben Burton
This software is released under the GNU General Public License.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@debian.org).