Regina Calculation Engine
Public Member Functions | List of all members
regina::NHomMarkedAbelianGroup Class Reference

Represents a homomorphism of finitely generated abelian groups. More...

#include <algebra/nmarkedabeliangroup.h>

Inheritance diagram for regina::NHomMarkedAbelianGroup:
regina::Output< NHomMarkedAbelianGroup >

Public Member Functions

 NHomMarkedAbelianGroup (const NMarkedAbelianGroup &dom, const NMarkedAbelianGroup &ran, const NMatrixInt &mat)
 Constructs a homomorphism from two marked abelian groups and a matrix that indicates where the generators are sent. More...
 
 NHomMarkedAbelianGroup (const NHomMarkedAbelianGroup &h)
 Copy constructor. More...
 
 ~NHomMarkedAbelianGroup ()
 Destructor. More...
 
bool isChainMap (const NHomMarkedAbelianGroup &other) const
 Determines whether this and the given homomorphism together form a chain map. More...
 
bool isCycleMap () const
 Is this at least a cycle map? If not, pretty much any further computations you try with this class will be give you nothing more than carefully-crafted garbage. More...
 
bool isEpic () const
 Is this an epic homomorphism? More...
 
bool isMonic () const
 Is this a monic homomorphism? More...
 
REGINA_DEPRECATED bool isIso () const
 A deprecated alternative to isIsomorphism(). More...
 
REGINA_INLINE_REQUIRED bool isIsomorphism () const
 Is this an isomorphism? More...
 
bool isZero () const
 Is this the zero map? More...
 
bool isIdentity () const
 Is this the identity automorphism? More...
 
REGINA_INLINE_REQUIRED const NMarkedAbelianGroupkernel () const
 Returns the kernel of this homomorphism. More...
 
REGINA_DEPRECATED const NMarkedAbelianGroupgetKernel () const
 Deprecated routine that returns the kernel of this homomorphism. More...
 
REGINA_INLINE_REQUIRED const NMarkedAbelianGroupcokernel () const
 Returns the cokernel of this homomorphism. More...
 
REGINA_DEPRECATED const NMarkedAbelianGroupgetCokernel () const
 Deprecated routine that returns the cokernel of this homomorphism. More...
 
REGINA_INLINE_REQUIRED const NMarkedAbelianGroupimage () const
 Returns the image of this homomorphism. More...
 
REGINA_DEPRECATED const NMarkedAbelianGroupgetImage () const
 Deprecated routine that returns the image of this homomorphism. More...
 
void writeTextShort (std::ostream &out) const
 Short text representation. More...
 
void writeTextLong (std::ostream &out) const
 A more detailed text representation of the homomorphism. More...
 
const NMarkedAbelianGroupdomain () const
 Returns the domain of this homomorphism. More...
 
REGINA_DEPRECATED const NMarkedAbelianGroupgetDomain () const
 Deprecated routine that returns the domain of this homomorphism. More...
 
const NMarkedAbelianGrouprange () const
 Returns the range of this homomorphism. More...
 
REGINA_DEPRECATED const NMarkedAbelianGroupgetRange () const
 Deprecated routine that returns the range of this homomorphism. More...
 
const NMatrixIntdefiningMatrix () const
 Returns the defining matrix for the homomorphism. More...
 
REGINA_DEPRECATED const NMatrixIntgetDefiningMatrix () const
 Deprecated routine that returns the defining matrix for the homomorphism. More...
 
const NMatrixIntreducedMatrix () const
 Returns the internal reduced matrix representing the homomorphism. More...
 
REGINA_DEPRECATED const NMatrixIntgetReducedMatrix () const
 Deprecated routine that returns the internal reduced matrix representing the homomorphism. More...
 
std::vector< NLargeIntegerevalCC (const std::vector< NLargeInteger > &input) const
 Evaluate the image of a vector under this homomorphism, using the original chain complexes' coordinates. More...
 
std::vector< NLargeIntegerevalSNF (const std::vector< NLargeInteger > &input) const
 Evaluate the image of a vector under this homomorphism, using the Smith normal form coordinates. More...
 
std::unique_ptr< NHomMarkedAbelianGroupinverseHom () const
 Returns the inverse to an NHomMarkedAbelianGroup. More...
 
std::unique_ptr< NHomMarkedAbelianGroupoperator* (const NHomMarkedAbelianGroup &X) const
 Returns the composition of two homomorphisms. More...
 
std::unique_ptr< NHomMarkedAbelianGrouptorsionSubgroup () const
 Returns an NHomMarkedAbelianGroup representing the induced map on the torsion subgroups. More...
 
void writeReducedMatrix (std::ostream &out) const
 Writes a human-readable version of the reduced matrix to the given output stream. 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...
 
REGINA_DEPRECATED std::string toString () const
 A deprecated alias for str(). More...
 
REGINA_DEPRECATED std::string toStringLong () const
 A deprecated alias for detail(). More...
 

Detailed Description

Represents a homomorphism of finitely generated abelian groups.

One initializes such a homomorphism by providing:

So for example, if the domain was initialized by the chain complex Z^a –A–> Z^b –B–> Z^c with mod p coefficients, and the range was initialized by Z^d –D–> Z^e –E–> Z^f with mod q coefficients, then the matrix needs to be an e-by-b matrix. Furthermore, you only obtain a well-defined homomorphism if this matrix extends to a cycle map, which this class assumes but which the user can confirm with isCycleMap(). Moreover, q should divide p: this allows for q > 0 and p = 0, which means the domain has Z coefficients and the range has mod q coefficients.

Todo:
Optimise (long-term): preImageOf in CC and SNF coordinates. This routine would return a generating list of elements in the preimage, thought of as an affine subspace. Or maybe just one element together with the kernel inclusion. IMO smarter to be a list because that way there's a more pleasant way to make it empty. Or we could have a variety of routines among these themes. Store some minimal data for efficient computations of preImage, eventually replacing the internals of inverseHom() with a more flexible set of tools. Also add an isInImage() in various coordinates.
Todo:
Optimise (long-term): writeTextShort() have completely different set of descriptors if an endomorphism domain = range (not so important at the moment though). New descriptors would include things like automorphism, projection, differential, finite order, etc.
Todo:
Optimise (long-term): Add map factorization, so that every homomorphism can be split as a composite of a projection followed by an inclusion. Add kernelInclusion(), coKerMap(), etc. Add a liftMap() call, i.e., a procedure to find a lift of a map if one exists.
Author
Ryan Budney

Constructor & Destructor Documentation

§ NHomMarkedAbelianGroup() [1/2]

regina::NHomMarkedAbelianGroup::NHomMarkedAbelianGroup ( const NMarkedAbelianGroup dom,
const NMarkedAbelianGroup ran,
const NMatrixInt mat 
)
inline

Constructs a homomorphism from two marked abelian groups and a matrix that indicates where the generators are sent.

The roles of the two groups and the matrix are described in detail in the NHomMarkedAbelianGroup class overview.

The matrix must be given in the chain-complex coordinates. Specifically, if the domain was defined via the chain complex Z^a –N1–> Z^b –M1–> Z^c and the range was defined via Z^d –N2–> Z^e –M2–> Z^f, then mat is an e-by-b matrix that describes a homomorphism from Z^b to Z^e.

In order for this to make sense as a homomorphism of the groups represented by the domain and range respectively, one requires img(mat*N1) to be a subset of img(N2). Similarly, ker(M1) must be sent into ker(M2). These facts are not checked, but are assumed as preconditions of this constructor.

Precondition
The matrix mat has the required dimensions e-by-b, gives img(mat*N1) as a subset of img(N2), and sends ker(M1) into ker(M2), as explained in the detailed notes above.
Parameters
domthe domain group.
ranthe range group.
matthe matrix that describes the homomorphism from dom to ran.

§ NHomMarkedAbelianGroup() [2/2]

regina::NHomMarkedAbelianGroup::NHomMarkedAbelianGroup ( const NHomMarkedAbelianGroup h)

Copy constructor.

Parameters
hthe homomorphism to clone.

§ ~NHomMarkedAbelianGroup()

regina::NHomMarkedAbelianGroup::~NHomMarkedAbelianGroup ( )
inline

Destructor.

Member Function Documentation

§ cokernel()

const NMarkedAbelianGroup & regina::NHomMarkedAbelianGroup::cokernel ( ) const
inline

Returns the cokernel of this homomorphism.

Returns
the cokernel of the homomorphism, as a marked abelian group.

§ definingMatrix()

const NMatrixInt & regina::NHomMarkedAbelianGroup::definingMatrix ( ) const
inline

Returns the defining matrix for the homomorphism.

Returns
the matrix that was used to define the homomorphism.

§ detail()

std::string regina::Output< NHomMarkedAbelianGroup , false >::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.

§ domain()

const NMarkedAbelianGroup & regina::NHomMarkedAbelianGroup::domain ( ) const
inline

Returns the domain of this homomorphism.

Returns
the domain that was used to define the homomorphism.

§ evalCC()

std::vector<NLargeInteger> regina::NHomMarkedAbelianGroup::evalCC ( const std::vector< NLargeInteger > &  input) const

Evaluate the image of a vector under this homomorphism, using the original chain complexes' coordinates.

This involves multiplication by the defining matrix.

Python:
Not available yet. This routine will be made accessible to Python in a future release.
Parameters
inputan input vector in the domain chain complex's coordinates, of length domain().M().columns().
Returns
the image of this vector in the range chain complex's coordinates, of length range().M().columns().

§ evalSNF()

std::vector<NLargeInteger> regina::NHomMarkedAbelianGroup::evalSNF ( const std::vector< NLargeInteger > &  input) const

Evaluate the image of a vector under this homomorphism, using the Smith normal form coordinates.

This is just multiplication by the reduced matrix, returning the empty vector if the input vector has the wrong dimensions.

Warning
Smith normal form coordinates are sensitive to the implementation of the Smith Normal Form, i.e., they are not canonical.
Python:
Not available yet. This routine will be made accessible to Python in a future release.
Parameters
inputan input vector in the domain SNF coordinates, of length domain().minNumberOfGenerators().
Returns
the image of this vector in the range chain complex's coordinates, of length range().minNumberOfGenerators().

§ getCokernel()

const NMarkedAbelianGroup & regina::NHomMarkedAbelianGroup::getCokernel ( ) const
inline

Deprecated routine that returns the cokernel of this homomorphism.

Deprecated:
This routine has been renamed to cokernel(). See the cokernel() documentation for further details.

§ getDefiningMatrix()

const NMatrixInt & regina::NHomMarkedAbelianGroup::getDefiningMatrix ( ) const
inline

Deprecated routine that returns the defining matrix for the homomorphism.

Deprecated:
This routine has been renamed to definingMatrix(). See the definingMatrix() documentation for further details.

§ getDomain()

const NMarkedAbelianGroup & regina::NHomMarkedAbelianGroup::getDomain ( ) const
inline

Deprecated routine that returns the domain of this homomorphism.

Deprecated:
This routine has been renamed to domain(). See the domain() documentation for further details.

§ getImage()

const NMarkedAbelianGroup & regina::NHomMarkedAbelianGroup::getImage ( ) const
inline

Deprecated routine that returns the image of this homomorphism.

Deprecated:
This routine has been renamed to image(). See the image() documentation for further details.

§ getKernel()

const NMarkedAbelianGroup & regina::NHomMarkedAbelianGroup::getKernel ( ) const
inline

Deprecated routine that returns the kernel of this homomorphism.

Deprecated:
This routine has been renamed to kernel(). See the kernel() documentation for further details.

§ getRange()

const NMarkedAbelianGroup & regina::NHomMarkedAbelianGroup::getRange ( ) const
inline

Deprecated routine that returns the range of this homomorphism.

Deprecated:
This routine has been renamed to domain(). See the domain() documentation for further details.

§ getReducedMatrix()

const NMatrixInt & regina::NHomMarkedAbelianGroup::getReducedMatrix ( ) const
inline

Deprecated routine that returns the internal reduced matrix representing the homomorphism.

Deprecated:
This routine has been renamed to reducedMatrix(). See the reducedMatrix() documentation for further details.

§ image()

const NMarkedAbelianGroup & regina::NHomMarkedAbelianGroup::image ( ) const
inline

Returns the image of this homomorphism.

Returns
the image of the homomorphism, as a marked abelian group.

§ inverseHom()

std::unique_ptr<NHomMarkedAbelianGroup> regina::NHomMarkedAbelianGroup::inverseHom ( ) const

Returns the inverse to an NHomMarkedAbelianGroup.

If this homomorphism is not invertible, this routine returns the zero homomorphism.

If you are computing with mod-p coefficients, this routine will further require that this invertible map preserves the UCT splitting of the group, i.e., it gives an isomorphism of the tensor product parts and the TOR parts. At present this suffices since we're only using this to construct maps between homology groups in different coordinate systems.

Returns
the inverse homomorphism, or the zero homomorphism if this is not invertible.

§ isChainMap()

bool regina::NHomMarkedAbelianGroup::isChainMap ( const NHomMarkedAbelianGroup other) const

Determines whether this and the given homomorphism together form a chain map.

Given two NHomMarkedAbelianGroups, you have two diagrams:

Z^a --N1--> Z^b --M1--> Z^c   Z^g --N3--> Z^h --M3--> Z^i
                  ^                             ^
                  |this.matrix                  |other.matrix
Z^d --N2--> Z^e --M2--> Z^f   Z^j --N4--> Z^k --M4--> Z^l

If c=g and f=j and M1=N3 and M2=N4, you can ask if these maps commute, i.e., whether you have a map of chain complexes.

Parameters
otherthe other homomorphism to analyse in conjunction with this.
Returns
true if and only if c=g, M1=N3, f=j, M2=N4, and the diagram commutes.

§ isCycleMap()

bool regina::NHomMarkedAbelianGroup::isCycleMap ( ) const

Is this at least a cycle map? If not, pretty much any further computations you try with this class will be give you nothing more than carefully-crafted garbage.

Technically, this routine only checks that cycles are sent to cycles, since it only has access to three of the four maps you need to verify you have a cycle map.

Returns
true if and only if this is a chain map.

§ isEpic()

bool regina::NHomMarkedAbelianGroup::isEpic ( ) const
inline

Is this an epic homomorphism?

Returns
true if this homomorphism is epic.

§ isIdentity()

bool regina::NHomMarkedAbelianGroup::isIdentity ( ) const

Is this the identity automorphism?

Returns
true if and only if the domain and range are defined via the same chain complexes and the induced map on homology is the identity.

§ isIso()

bool regina::NHomMarkedAbelianGroup::isIso ( ) const
inline

A deprecated alternative to isIsomorphism().

Deprecated:
This routine will be removed in a future version of Regina; please use the identical routine isIsomorphism() instead.
Returns
true if this homomorphism is an isomorphism.

§ isIsomorphism()

bool regina::NHomMarkedAbelianGroup::isIsomorphism ( ) const
inline

Is this an isomorphism?

Returns
true if this homomorphism is an isomorphism.

§ isMonic()

bool regina::NHomMarkedAbelianGroup::isMonic ( ) const
inline

Is this a monic homomorphism?

Returns
true if this homomorphism is monic.

§ isZero()

bool regina::NHomMarkedAbelianGroup::isZero ( ) const
inline

Is this the zero map?

Returns
true if this homomorphism is the zero map.

§ kernel()

const NMarkedAbelianGroup & regina::NHomMarkedAbelianGroup::kernel ( ) const
inline

Returns the kernel of this homomorphism.

Returns
the kernel of the homomorphism, as a marked abelian group.

§ operator*()

std::unique_ptr<NHomMarkedAbelianGroup> regina::NHomMarkedAbelianGroup::operator* ( const NHomMarkedAbelianGroup X) const

Returns the composition of two homomorphisms.

Precondition
the homomorphisms must be composable, meaning that the range of X must have the same presentation matrices as the domain of this homomorphism.
Parameters
Xthe homomorphism to compose this with.
Returns
a newly created composite homomorphism.

§ range()

const NMarkedAbelianGroup & regina::NHomMarkedAbelianGroup::range ( ) const
inline

Returns the range of this homomorphism.

Returns
the range that was used to define the homomorphism.

§ reducedMatrix()

const NMatrixInt & regina::NHomMarkedAbelianGroup::reducedMatrix ( ) const
inline

Returns the internal reduced matrix representing the homomorphism.

This is where the rows/columns of the matrix represent first the free generators, then the torsion summands in the order of the invariant factors:

        Z^d + Z_{d0} + ... + Z_{dk}

where:

  • d 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.
Returns
a copy of the internal representation of the homomorphism.

§ str()

std::string regina::Output< NHomMarkedAbelianGroup , false >::str ( ) const
inherited

Returns a short text representation of this object.

This text should be human-readable, should fit on a single line, and should not end with a newline. Where possible, it should use plain ASCII characters.

Python:
In addition to str(), this is also used as the Python "stringification" function __str__().
Returns
a short text representation of this object.

§ torsionSubgroup()

std::unique_ptr<NHomMarkedAbelianGroup> regina::NHomMarkedAbelianGroup::torsionSubgroup ( ) const

Returns an NHomMarkedAbelianGroup representing the induced map on the torsion subgroups.

§ toString()

REGINA_DEPRECATED std::string regina::Output< NHomMarkedAbelianGroup , false >::toString ( ) const
inherited

A deprecated alias for str().

Deprecated:
This routine has (at long last) been deprecated; use the simpler-to-type str() instead.
Returns
a short text representation of this object.

§ toStringLong()

REGINA_DEPRECATED std::string regina::Output< NHomMarkedAbelianGroup , false >::toStringLong ( ) const
inherited

A deprecated alias for detail().

Deprecated:
This routine has (at long last) been deprecated; use the simpler-to-type detail() instead.
Returns
a long text representation of this object.

§ utf8()

std::string regina::Output< NHomMarkedAbelianGroup , false >::utf8 ( ) const
inherited

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

Like str(), this text should be human-readable, should fit on a single line, and should not end with a newline. In addition, it may use unicode characters to make the output more pleasant to read. This string will be encoded in UTF-8.

Returns
a short text representation of this object.

§ writeReducedMatrix()

void regina::NHomMarkedAbelianGroup::writeReducedMatrix ( std::ostream &  out) const

Writes a human-readable version of the reduced matrix to the given output stream.

This is a description of the homomorphism in some specific coordinates at present only meant to be internal to NHomMarkedAbelianGroup. At present, these coordinates have the torsion factors of the group appearing first, followed by the free factors.

Python:
The out argument is missing; instead this is assumed to be standard output.
Parameters
outthe output stream.

§ writeTextLong()

void regina::NHomMarkedAbelianGroup::writeTextLong ( std::ostream &  out) const

A more detailed text representation of the homomorphism.

Parameters
outthe stream to write to.

§ writeTextShort()

void regina::NHomMarkedAbelianGroup::writeTextShort ( std::ostream &  out) const

Short text representation.

This will state some basic properties of the homomorphism, such as:

  • whether the map is the identity;
  • whether the map is an isomorphism;
  • whether the map is monic or epic;
  • if it is not monic, describes the kernel;
  • if it is not epic, describes the co-kernel;
  • if it is neither monic nor epic, describes the image.
Parameters
outthe stream to write to.

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

Copyright © 1999-2016, 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@maths.uq.edu.au).