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

#include <algebra/markedabeliangroup.h>

Inheritance diagram for regina::HomMarkedAbelianGroup:

Public Member Functions
	HomMarkedAbelianGroup (MarkedAbelianGroup dom, MarkedAbelianGroup codom, MatrixInt mat)
	Constructs a homomorphism from two marked abelian groups and a matrix that indicates where the generators are sent. More...

	HomMarkedAbelianGroup (const HomMarkedAbelianGroup &)=default
	Creates a clone of the given homomorphism. More...

	HomMarkedAbelianGroup (HomMarkedAbelianGroup &&src) noexcept=default
	Moves the contents of the given homomorphism into this new homomorphism. More...

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

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

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

bool	isChainMap (const HomMarkedAbelianGroup &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...

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

const AbelianGroup &	kernel () const
	Returns the kernel of this homomorphism. More...

const AbelianGroup &	cokernel () const
	Returns the cokernel of this homomorphism. More...

const AbelianGroup &	image () const
	Returns the image of this homomorphism. More...

std::string	summary () const
	Returns a very brief summary of the type of map. More...

void	summary (std::ostream &out) const
	Writes a very brief summary of the type of map to the given output stream. More...

void	writeTextShort (std::ostream &out) const
	Writes a short text representation of this object to the given output stream. More...

void	writeTextLong (std::ostream &out) const
	Writes a detailed text representation of this object to the given output stream. More...

const MarkedAbelianGroup &	domain () const
	Returns the domain of this homomorphism. More...

const MarkedAbelianGroup &	codomain () const
	Returns the codomain of this homomorphism. More...

const MatrixInt &	definingMatrix () const
	Returns the defining matrix for the homomorphism. More...

const MatrixInt &	reducedMatrix () const
	Returns the internal reduced matrix representing the homomorphism. More...

Vector< Integer >	evalCC (const Vector< Integer > &input) const
	Evaluate the image of a vector under this homomorphism, using the original chain complexes' coordinates. More...

Vector< Integer >	evalSNF (const Vector< Integer > &input) const
	Evaluate the image of a vector under this homomorphism, using the Smith normal form coordinates. More...

HomMarkedAbelianGroup	inverseHom () const
	Returns the inverse to a HomMarkedAbelianGroup. More...

HomMarkedAbelianGroup	operator* (const HomMarkedAbelianGroup &X) const
	Returns the composition of two homomorphisms. More...

HomMarkedAbelianGroup	operator* (HomMarkedAbelianGroup &&X) const
	Returns the composition of two homomorphisms. More...

HomMarkedAbelianGroup	torsionSubgroup () const
	Returns a HomMarkedAbelianGroup representing the induced map on the torsion subgroups. More...

void	writeReducedMatrix (std::ostream &out) const
	Deprecated routine that 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...

Detailed Description

Represents a homomorphism of finitely generated abelian groups.

One initializes such a homomorphism by providing:

two finitely generated abelian groups, which act as domain and codomain;
a matrix describing the linear map between the free abelian groups in the centres of the respective chain complexes that were used to define the domain and codomain. If the abelian groups are computed via homology with coefficients, the codomain coefficients must be a quotient of the domain coefficients.

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 codomain 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 codomain has mod q coefficients.

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.

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

◆ HomMarkedAbelianGroup() [1/3]

regina::HomMarkedAbelianGroup::HomMarkedAbelianGroup	(	MarkedAbelianGroup	dom,
		MarkedAbelianGroup	codom,
		MatrixInt	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 HomMarkedAbelianGroup 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 codomain 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 codomain 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

dom	the domain group.
codom	the codomain group.
mat	the matrix that describes the homomorphism from dom to ran.

◆ HomMarkedAbelianGroup() [2/3]

regina::HomMarkedAbelianGroup::HomMarkedAbelianGroup ( const HomMarkedAbelianGroup & )

default

Creates a clone of the given homomorphism.

◆ HomMarkedAbelianGroup() [3/3]

regina::HomMarkedAbelianGroup::HomMarkedAbelianGroup ( HomMarkedAbelianGroup && src )

defaultnoexcept

Moves the contents of the given homomorphism into this new homomorphism.

This is a fast (constant time) operation.

The homomorphism that was passed will no longer be usable.

Member Function Documentation

◆ codomain()

const MarkedAbelianGroup & regina::HomMarkedAbelianGroup::codomain ( ) const

inline

Returns the codomain of this homomorphism.

Returns: the codomain that was used to define the homomorphism.

◆ cokernel()

const AbelianGroup & regina::HomMarkedAbelianGroup::cokernel ( ) const

inline

Returns the cokernel of this homomorphism.

Returns: the cokernel of the homomorphism.

◆ definingMatrix()

const MatrixInt & regina::HomMarkedAbelianGroup::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< HomMarkedAbelianGroup , 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 MarkedAbelianGroup & regina::HomMarkedAbelianGroup::domain ( ) const

inline

Returns the domain of this homomorphism.

Returns: the domain that was used to define the homomorphism.

◆ evalCC()

Vector< Integer > regina::HomMarkedAbelianGroup::evalCC ( const Vector< Integer > & input ) const

inline

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

This involves multiplication by the defining matrix.

Exceptions

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

Parameters

input an input vector in the domain chain complex's coordinates, of length domain().M().columns().

Returns: the image of this vector in the codomain chain complex's coordinates, of length codomain().M().columns().

◆ evalSNF()

Vector< Integer > regina::HomMarkedAbelianGroup::evalSNF ( const Vector< Integer > & 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.

Warning: Smith normal form coordinates are sensitive to the implementation of the Smith Normal Form, i.e., they are not canonical.

Exceptions

InvalidArgument The given vector was not in domain SNF coordinates; that is, its length was not domain().snfRank().

Parameters

input an input vector in the domain SNF coordinates, of length domain().snfRank().

Returns: the image of this vector in the codomain chain complex's coordinates, of length codomain().snfRank().

◆ image()

const AbelianGroup & regina::HomMarkedAbelianGroup::image ( ) const

inline

Returns the image of this homomorphism.

Returns: the image of the homomorphism.

◆ inverseHom()

HomMarkedAbelianGroup regina::HomMarkedAbelianGroup::inverseHom ( ) const

Returns the inverse to a HomMarkedAbelianGroup.

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::HomMarkedAbelianGroup::isChainMap ( const HomMarkedAbelianGroup & other ) const

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

Given two HomMarkedAbelianGroups, 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

other the 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::HomMarkedAbelianGroup::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::HomMarkedAbelianGroup::isEpic ( ) const

inline

Is this an epic homomorphism?

Returns: true if this homomorphism is epic.

◆ isIdentity()

bool regina::HomMarkedAbelianGroup::isIdentity ( ) const

Is this the identity automorphism?

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

◆ isIsomorphism()

bool regina::HomMarkedAbelianGroup::isIsomorphism ( ) const

inline

Is this an isomorphism?

Returns: true if this homomorphism is an isomorphism.

◆ isMonic()

bool regina::HomMarkedAbelianGroup::isMonic ( ) const

inline

Is this a monic homomorphism?

Returns: true if this homomorphism is monic.

◆ isZero()

bool regina::HomMarkedAbelianGroup::isZero ( ) const

inline

Is this the zero map?

Returns: true if this homomorphism is the zero map.

◆ kernel()

const AbelianGroup & regina::HomMarkedAbelianGroup::kernel ( ) const

inline

Returns the kernel of this homomorphism.

Returns: the kernel of the homomorphism.

◆ operator*() [1/2]

HomMarkedAbelianGroup regina::HomMarkedAbelianGroup::operator* ( const HomMarkedAbelianGroup & X ) const

Returns the composition of two homomorphisms.

Precondition: the homomorphisms must be composable, meaning that the codomain of X must have the same presentation matrices as the domain of this homomorphism.

Parameters

X	the homomorphism to compose this with.

Returns: the composite homomorphism.

◆ operator*() [2/2]

HomMarkedAbelianGroup regina::HomMarkedAbelianGroup::operator* ( HomMarkedAbelianGroup && X ) const

Returns the composition of two homomorphisms.

Precondition: the homomorphisms must be composable, meaning that the codomain of X must have the same presentation matrices as the domain of this homomorphism.

Parameters

X	the homomorphism to compose this with.

Returns: the composite homomorphism.

◆ operator=() [1/2]

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

default

Sets this to be a clone of the given homomorphism.

Returns: a reference to this homomorphism.

◆ operator=() [2/2]

HomMarkedAbelianGroup & regina::HomMarkedAbelianGroup::operator= ( HomMarkedAbelianGroup && )

defaultnoexcept

Moves the contents of the given homomorphism to this homomorphism.

This is a fast (constant time) operation.

The homomorphism that was passed will no longer be usable.

Returns: a reference to this homomorphism.

◆ reducedMatrix()

const MatrixInt & regina::HomMarkedAbelianGroup::reducedMatrix ( ) const

inline

Returns the internal reduced matrix representing the homomorphism.

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

        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.

Returns: a copy of the internal representation of the homomorphism.

◆ str()

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

◆ summary() [1/2]

std::string regina::HomMarkedAbelianGroup::summary ( ) const

Returns a very brief summary of the type of map.

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.

Returns: a brief summary.

◆ summary() [2/2]

void regina::HomMarkedAbelianGroup::summary ( std::ostream & out ) const

Writes a very brief summary of the type of map to the given output stream.

This writes exactly the same information as the no-argument variant of summary() returns; see that routine for further details.

Python: Not present, but you can call the no-argument variant of summary instead(), which returns this same information in string form.

Parameters

out	the output stream to which to write.

◆ swap()

void regina::HomMarkedAbelianGroup::swap ( HomMarkedAbelianGroup & other )

noexcept

Swaps the contents of this and the given homomorphism.

Parameters

other the homomorphism whose contents should be swapped with this.

◆ torsionSubgroup()

HomMarkedAbelianGroup regina::HomMarkedAbelianGroup::torsionSubgroup ( ) const

Returns a HomMarkedAbelianGroup representing the induced map on the torsion subgroups.

◆ utf8()

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

◆ writeReducedMatrix()

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

Deprecated routine that 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 HomMarkedAbelianGroup. At present, these coordinates have the torsion factors of the group appearing first, followed by the free factors.

Deprecated:: All of the information that this routine outputs is now written by writeTextLong() and returned in string form by detail(). Use those routines instead.

Python: Not present; instead use detail(), which returns a string including all this information (plus a little more).

Parameters

out	the output stream.

◆ writeTextLong()

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

Writes a detailed text representation of this object to the given output stream.

Python: Not present; use detail() instead.

Parameters

out	the stream to write to.

◆ writeTextShort()

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

Writes a short text representation of this object to the given output stream.

Python: Not present; use str() instead.

Parameters

out	the stream to write to.

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

algebra/markedabeliangroup.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ HomMarkedAbelianGroup() [1/3]

◆ HomMarkedAbelianGroup() [2/3]

◆ HomMarkedAbelianGroup() [3/3]

Member Function Documentation

◆ codomain()

◆ cokernel()

◆ definingMatrix()

◆ detail()

◆ domain()

◆ evalCC()

◆ evalSNF()

◆ image()

◆ inverseHom()

◆ isChainMap()

◆ isCycleMap()

◆ isEpic()

◆ isIdentity()

◆ isIsomorphism()

◆ isMonic()

◆ isZero()

◆ kernel()

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ reducedMatrix()

◆ str()

◆ summary() [1/2]

◆ summary() [2/2]

◆ swap()

◆ torsionSubgroup()

◆ utf8()

◆ writeReducedMatrix()

◆ writeTextLong()

◆ writeTextShort()