regina::NMarkedAbelianGroup Class Reference
[Algebraic Structures]

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

#include <nmarkedabeliangroup.h>

Inheritance diagram for regina::NMarkedAbelianGroup:

regina::ShareableObject regina::boost::noncopyable

List of all members.

Public Member Functions

 NMarkedAbelianGroup (const NMatrixInt &M, const NMatrixInt &N)
 Creates a marked abelian group from a chain complex.
 NMarkedAbelianGroup (const NMarkedAbelianGroup &cloneMe)
 Creates a clone of the given group.
virtual ~NMarkedAbelianGroup ()
 Destroys the 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 NMarkedAbelianGroup &other) const
 Determines whether this and the given abelian group are isomorphic.
virtual void writeTextShort (std::ostream &out) const
 The text representation will be of the form 3 Z + 4 Z_2 + Z_120.
std::vector< NLargeIntegergetFreeRep (unsigned long index) const
 Returns the requested free generator.
std::vector< NLargeIntegergetTorsionRep (unsigned long index) const
 Returns the requested generator of the torsion subgroup.
std::vector< NLargeIntegergetSNFIsoRep (const std::vector< NLargeInteger > &v) const
 Expresses the given vector as a combination of free and torsion generators.
const NMatrixIntgetMRB () const
 Returns a change-of-basis matrix for the Smith normal form of M.
const NMatrixIntgetMRBi () const
 Returns an inverse change-of-basis matrix for the Smith normal form of M.
const NMatrixIntgetMCB () const
 Returns a change-of-basis matrix for the Smith normal form of M.
const NMatrixIntgetMCBi () const
 Returns an inverse change-of-basis matrix for the Smith normal form of M.
const NMatrixIntgetNRB () const
 Returns a change-of-basis matrix for the Smith normal form of the internal presentation matrix.
const NMatrixIntgetNRBi () const
 Returns an inverse change-of-basis matrix for the Smith normal form of the internal presentation matrix.
const NMatrixIntgetNCB () const
 Returns a change-of-basis matrix for the Smith normal form of the internal presentation matrix.
const NMatrixIntgetNCBi () const
 Returns an inverse change-of-basis matrix for the Smith normal form of the internal presentation matrix.
unsigned long getRankM () const
 Returns the rank of the defining matrix M.
unsigned long getFreeLoc () const
 Returns the index of the first free generator in the Smith normal form of the internal presentation matrix.
unsigned long getTorsionLoc () const
 Returns the index of the first torsion generator in the Smith normal form of the internal presentation matrix.
const NMatrixIntgetM () const
 Returns the `right' matrix used in defining the chain complex.
const NMatrixIntgetN () const
 Returns the `left' matrix used in defining the chain complex.


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. The abelian group is the kernel of M mod the image of N.

In other words, we are computing the homology of the chain complex Z^a --N--> Z^b --M--> Z^c where a=N.columns(), M.columns()=b=N.rows(), and c=M.rows().

This class allows one 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 allow one to not only represent homology groups, but it gives the foundation for studying maps between homology groups. This is used in the computation of the torsion H_1 form coming from Poincare Duality.

Some routines in this class refer to the internal presentation matrix. This is a proper presentation matrix for the abelian group, and is created by constructing the product getMRBi() * N, and then removing the first getRankM() rows.

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

Constructor & Destructor Documentation

regina::NMarkedAbelianGroup::NMarkedAbelianGroup ( const NMatrixInt M,
const NMatrixInt N 
)

Creates a marked abelian group from a chain complex.

See the class notes for details.

Precondition:
M.columns() = N.rows().

The product M*N = 0.

Parameters:
M `right' matrix in chain complex
N `left' matrix in chain complex

regina::NMarkedAbelianGroup::NMarkedAbelianGroup ( const NMarkedAbelianGroup cloneMe  )  [inline]

Creates a clone of the given group.

Parameters:
cloneMe the group to clone.

regina::NMarkedAbelianGroup::~NMarkedAbelianGroup (  )  [inline, virtual]

Destroys the group.


Member Function Documentation

unsigned long regina::NMarkedAbelianGroup::getFreeLoc (  )  const [inline]

Returns the index of the first free generator in the Smith normal form of the internal presentation matrix.

See the class overview for details.

Returns:
the index of the first free generator.

std::vector<NLargeInteger> regina::NMarkedAbelianGroup::getFreeRep ( unsigned long  index  )  const

Returns the requested free generator.

As described in the class overview, this marked abelian group is defined by matrices M and N where M*N = 0. If M is an m by l matrix and N is an l by n matrix, then this routine returns the (index)th free generator of ker(M)/img(N) in Z^l.

Python:
The return value will be a python list.
Parameters:
index specifies which free generator to look up; this must be between 0 and getRank()-1 inclusive.
Returns:
the coordinates of the free generator in the nullspace of M; this vector will have length M.columns() (or equivalently, N.rows()).

const NLargeInteger & regina::NMarkedAbelianGroup::getInvariantFactor ( unsigned long  index  )  const [inline]

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

See the NMarkedAbelianGroup 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.

const NMatrixInt & regina::NMarkedAbelianGroup::getM (  )  const [inline]

Returns the `right' matrix used in defining the chain complex.

This is a copy of 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.

const NMatrixInt & regina::NMarkedAbelianGroup::getMCB (  )  const [inline]

Returns a change-of-basis matrix for the Smith normal form of M.

This is one of several routines that returns information on how we determine the isomorphism-class of this group.

Recall from the class overview that this marked abelian group is defined by matrices M and N, where M*N = 0.

Returns:
the matrix getMCB() as described above.

const NMatrixInt & regina::NMarkedAbelianGroup::getMCBi (  )  const [inline]

Returns an inverse change-of-basis matrix for the Smith normal form of M.

This is one of several routines that returns information on how we determine the isomorphism-class of this group.

Recall from the class overview that this marked abelian group is defined by matrices M and N, where M*N = 0.

Returns:
the matrix getMCBi() as described above.

const NMatrixInt & regina::NMarkedAbelianGroup::getMRB (  )  const [inline]

Returns a change-of-basis matrix for the Smith normal form of M.

This is one of several routines that returns information on how we determine the isomorphism-class of this group.

Recall from the class overview that this marked abelian group is defined by matrices M and N, where M*N = 0.

Returns:
the matrix getMRB() as described above.

const NMatrixInt & regina::NMarkedAbelianGroup::getMRBi (  )  const [inline]

Returns an inverse change-of-basis matrix for the Smith normal form of M.

This is one of several routines that returns information on how we determine the isomorphism-class of this group.

Recall from the class overview that this marked abelian group is defined by matrices M and N, where M*N = 0.

Returns:
the matrix getMRBi() as described above.

const NMatrixInt & regina::NMarkedAbelianGroup::getN (  )  const [inline]

Returns the `left' matrix used in defining the chain complex.

This is a copy of 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.

const NMatrixInt & regina::NMarkedAbelianGroup::getNCB (  )  const [inline]

Returns a change-of-basis matrix for the Smith normal form of the internal presentation matrix.

This is one of several routines that returns information on how we determine the isomorphism-class of this group.

For details on the internal presentation matrix, see the class overview. If P is the internal presentation matrix, then:

Returns:
the matrix getNCB() as described above.

const NMatrixInt & regina::NMarkedAbelianGroup::getNCBi (  )  const [inline]

Returns an inverse change-of-basis matrix for the Smith normal form of the internal presentation matrix.

This is one of several routines that returns information on how we determine the isomorphism-class of this group.

For details on the internal presentation matrix, see the class overview. If P is the internal presentation matrix, then:

Returns:
the matrix getNCBi() as described above.

const NMatrixInt & regina::NMarkedAbelianGroup::getNRB (  )  const [inline]

Returns a change-of-basis matrix for the Smith normal form of the internal presentation matrix.

This is one of several routines that returns information on how we determine the isomorphism-class of this group.

For details on the internal presentation matrix, see the class overview. If P is the internal presentation matrix, then:

Returns:
the matrix getNRB() as described above.

const NMatrixInt & regina::NMarkedAbelianGroup::getNRBi (  )  const [inline]

Returns an inverse change-of-basis matrix for the Smith normal form of the internal presentation matrix.

This is one of several routines that returns information on how we determine the isomorphism-class of this group.

For details on the internal presentation matrix, see the class overview. If P is the internal presentation matrix, then:

Returns:
the matrix getNRBi() as described above.

unsigned long regina::NMarkedAbelianGroup::getNumberOfInvariantFactors (  )  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 NMarkedAbelianGroup class notes for further details.

Returns:
the number of invariant factors.

unsigned regina::NMarkedAbelianGroup::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 long regina::NMarkedAbelianGroup::getRankM (  )  const [inline]

Returns the rank of the defining matrix M.

The matrix M is the `right' matrix used in defining the chain complex. See the class overview for further details.

Returns:
the rank of the defining matrix M.

std::vector<NLargeInteger> regina::NMarkedAbelianGroup::getSNFIsoRep ( const std::vector< NLargeInteger > &  v  )  const

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

Recall that this marked abelian was defined by matrices M and N with M*N=0; suppose that M is an m by l matrix and N is an l by n matrix. This abelian group is then the quotient ker(M)/img(N) in Z^l.

When it is constructed, this group is computed to be isomorphic to some Z^d + Z_{d0} + ... + Z_{dk}, where:

  • d is the number of free generators, as returned by getRank();
  • d1, ..., dk are the invariant factors that describe the torsion elements of the group, where 1 < d1 | d2 | ... | dk.

This routine takes a single argument v, which must be a vector in Z^l.

If v belongs to ker(M), this routine describes how it projects onto the group ker(M)/img(N). Specifically, it returns a vector of length d + k, where:

  • the first d elements describe the projection of v to the free component Z^d;
  • the remaining k elements describe the projection of v to the torsion component Z_{d1} + ... + Z_{dk}. These elements are returned as non-negative integers modulo d1, ..., dk respectively.

In other words, suppose v belongs to ker(M) and getSNFIsoRep(v) returns the vector (a1, ..., ad, b1, ..., bk). Suppose furthermore that the free generators returned by getFreeRep(0..(d-1)) are f1, ..., fd respectively, and that the torsion generators returned by getTorsionRep(0..(k-1)) are t1, ..., tk respectively. Then v = a1.f1 + ... + ad.fd + b1.t1 + ... + bk.tk modulo img(N).

If v does not belong to ker(M), this routine simply returns the empty vector.

Precondition:
Vector v has length M.columns(), or equivalently N.rows().
Python:
Both v and the return value are python lists.
Parameters:
v a vector of length M.columns().
Returns:
a vector that describes v in the standard Z^d + Z_{d1} + ... + Z_{dk} form, or the empty vector if v is not in the kernel of M.

unsigned long regina::NMarkedAbelianGroup::getTorsionLoc (  )  const [inline]

Returns the index of the first torsion generator in the Smith normal form of the internal presentation matrix.

See the class overview for details.

Returns:
the index of the first torsion generator.

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

std::vector<NLargeInteger> regina::NMarkedAbelianGroup::getTorsionRep ( unsigned long  index  )  const

Returns the requested generator of the torsion subgroup.

As described in the class overview, this marked abelian group is defined by matrices M and N where M*N = 0. If M is an m by l matrix and N is an l by n matrix, then this routine returns the (index)th torsion generator of ker(M)/img(N) in Z^l.

Python:
The return value will be a python list.
Parameters:
index specifies which generator in the torsion subgroup; this must be at least 0 and strictly less than the number of non-trivial invariant factors.
Returns:
the coordinates of the generator in the nullspace of M; this vector will have length M.columns() (or equivalently, N.rows()).

bool regina::NMarkedAbelianGroup::isTrivial (  )  const [inline]

Determines whether this is the trivial (zero) group.

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

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

virtual void regina::NMarkedAbelianGroup::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 NMarkedAbelianGroup notes.

Parameters:
out the stream to write to.

Implements regina::ShareableObject.


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

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