A specialised class that computes a large amount of detailed homological information for a 3-manifold triangulation. More...

#include <triangulation/dim3/homologicaldata.h>

Inheritance diagram for regina::HomologicalData:

Public Member Functions
	HomologicalData (const Triangulation< 3 > &input)
	Takes as input a triangulation. More...

	HomologicalData (const HomologicalData &)=default
	Creates a new copy of the given object. More...

	HomologicalData (HomologicalData &&) noexcept=default
	Moves the contents of the given object into this new object. More...

HomologicalData &	operator= (const HomologicalData &)=default
	Sets this to be a copy of the given object. More...

HomologicalData &	operator= (HomologicalData &&) noexcept=default
	Moves the contents of the given object into this object. More...

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

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

const MarkedAbelianGroup &	homology (unsigned q)
	This routine gives access to the manifold's homology computed with the regular CW-decomposition. More...

const MarkedAbelianGroup &	bdryHomology (unsigned q)
	This routine gives access to the homology of the boundary of the manifold, computed with the regular CW-decomposition. More...

const HomMarkedAbelianGroup &	bdryHomologyMap (unsigned q)
	This routine gives access to the homomorphism from the homology of the boundary to the homology of the manifold. More...

const MarkedAbelianGroup &	dualHomology (unsigned q)
	This routine gives access to the manifold's homology computed with the dual CW-decomposition. More...

const HomMarkedAbelianGroup &	h1CellAp ()
	Returns the isomorphism from dualHomology(1) to homology(1) given by a cellular approximation to the identity map on the manifold. More...

unsigned long	countStandardCells (unsigned dimension)
	Returns the number of cells of the given dimension in the standard genuine CW-decomposition of the manifold. More...

unsigned long	countDualCells (unsigned dimension)
	Returns the number of cells of the given dimension in the dual CW-decomposition of the manifold. More...

unsigned long	countBdryCells (unsigned dimension)
	Returns the number of cells of the given dimension in the standard CW-decomposition of the boundary of the manifold. More...

long	eulerChar ()
	The proper Euler characteristic of the manifold, computed from the dual CW-decomposition. More...

const std::vector< std::pair< Integer, std::vector< unsigned long > > > &	torsionRankVector ()
	Returns the torsion form rank vector. More...

const std::string &	torsionRankVectorString ()
	Same as torsionRankVector() but returns as a human-readable string. More...

const std::vector< LargeInteger > &	torsionSigmaVector ()
	Returns the 2-torsion sigma vector. More...

const std::string &	torsionSigmaVectorString ()
	Same as torsionSigmaVector() but returns as a human-readable string. More...

const std::vector< std::pair< Integer, std::vector< int > > > &	torsionLegendreSymbolVector ()
	Returns the odd p-torsion Legendre symbol vector. More...

const std::string &	torsionLegendreSymbolVectorString ()
	Same as torsionLegendreSymbolVector() but returns as a human-readable string. More...

bool	formIsHyperbolic ()
	Returns true iff torsion linking form is ‘hyperbolic’ in the linking-form sense of the word. More...

bool	formIsSplit ()
	Returns true iff the torsion linking form is split. More...

bool	formSatKK ()
	Returns true iff the torsion linking form satisfies the Kawauchi-Kojima 2-torsion condition. More...

const std::string &	embeddabilityComment ()
	Returns a comment on whether the manifold might embed in a homology 3-sphere or 4-sphere. More...

void	writeTextLong (std::ostream &out) const
	A default implementation for detailed output. 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

A specialised class that computes a large amount of detailed homological information for a 3-manifold triangulation.

This class is both heavyweight and specialised. If you just wish to compute homology or Euler characteristic, or even map faces of the skeleton to classes in the homology groups, the Triangulation class has simpler and slicker member functions that can do this for you. See for example the Triangulation functions homology(), eulerCharTri(), eulerCharManifold(), and markedHomology().

The most important thing that HomologicalData adds is the ability to work with the torsion linking form. Be aware however that the code that computes the torsion linking form includes some floating-point arithmetic, and this could be subject to round-off error. Such errors are not expected, since the floating-point code is simply distinguishing different multiples of a known irrational, but nevertheless these results should be considered non-rigorous.

Currently, the information computed by HomologicalData includes:

the manifold's homology;
the boundary's homology;
the map from boundary -> manifold;
the dual cellular homology;
the isomorphism on H1 from the dual cellular homology to the regular cellular homology;
the H1 torsion form;
the Kawauchi-Kojima invariants of torsion linking forms.

This class takes a "least effort" approach to all computations. It only computes what is neccessary for your requests. It also keeps a record of all previous computations you've made. If a computation can be sped up by not recomputing some data, it takes that short-cut.

All these algorithms use two transverse CW decompositions of the manifold. They correspond to the (possibly ideal) triangulation native to Regina, and the dual polyhedral (CW) decomposition which appears in Seifert and Threlfall's textbook.

In the following lists we describe the canonical ordering of both the cells and the dual cells of the given triangulation.

First we list the cell orderings for the standard CW decomposition, which most closely resembles the ideal triangulation.

0-cells: The non-ideal vertices given in the order vertices.begin() to vertices.end(), followed by the ideal endpoints of the edges edges.begin() to edges.end() with endpoints for each edge taken in the order 0,1.
1-cells: edges.begin() to edges.end(), followed by the ideal edges of faces.begin() to faces.end() in order 0,1,2.
2-cells: faces.begin() to faces.end(), followed by the ideal faces of tetrahedra.begin() through tetrahedra.end() in order 0,1,2,3.
3-cells: tetrahedra.begin() through tetrahedra.end().

Next we list the cell orderings for the dual CW decomposition: if the standard CW decomposition came from a morse function f, this would be the one for -f.

0-cells: tetrahedra.begin() through tetrahedra.end().
1-cells: the non-boundary faces.begin() through faces.end().
2-cells: the non-boundary edges.begin() through edges.end().
3-cells: the non-boundary, non-ideal vertices.begin() through vertices.end().

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. Be aware, however, that it contains an enormous amount of internal data, and even moves will still be relatively expensive - you should try to use just the one HomologicalData object and not copy or move it at all, if possible.

This class will eventually be removed in a future release of Regina.

Author: Ryan Budney

Constructor & Destructor Documentation

◆ HomologicalData() [1/3]

regina::HomologicalData::HomologicalData ( const Triangulation< 3 > & input )

inline

Takes as input a triangulation.

This class will maintain a fixed snapshot of the given triangulation as it is at this point in time. You are free to edit or even destroy the input triangulation later on; if you do then this HomologicalData object will automatically take its own deep copy of the original and continue to use that for its own internal reference.

Parameters

input the triangulation to use.

◆ HomologicalData() [2/3]

regina::HomologicalData::HomologicalData ( const HomologicalData & )

default

Creates a new copy of the given object.

This constructor induces a deep copy of the given object; moreover, this is expensive since HomologicalData objects are very large.

◆ HomologicalData() [3/3]

regina::HomologicalData::HomologicalData ( HomologicalData && )

defaultnoexcept

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

This operation is constant time, but it is still expensive constant time because HomologicalData objects are very large.

The object that was passed will no longer be usable.

Member Function Documentation

◆ bdryHomology()

const MarkedAbelianGroup & regina::HomologicalData::bdryHomology ( unsigned q )

This routine gives access to the homology of the boundary of the manifold, computed with the regular CW-decomposition.

Parameters

q	the dimension of the homology group: can be 0, 1 or 2.

Returns: the q-th boundary homology group, in standard cellular homology coordinates

◆ bdryHomologyMap()

const HomMarkedAbelianGroup & regina::HomologicalData::bdryHomologyMap ( unsigned q )

This routine gives access to the homomorphism from the homology of the boundary to the homology of the manifold.

Parameters

q	the dimension of the map: can be 0, 1 or 2.

Returns: the map from H_q of the boundary to H_q of the manifold, computed in standard coordinates.

◆ countBdryCells()

unsigned long regina::HomologicalData::countBdryCells ( unsigned dimension )

inline

Returns the number of cells of the given dimension in the standard CW-decomposition of the boundary of the manifold.

This is a subcomplex of the complex used in countStandardCells().

Parameters

dimension the dimension of the cells in question; this must be 0, 1 or 2.

Returns: the number of cells of the given dimension in the standard CW-decomposition of the boundary.

◆ countDualCells()

unsigned long regina::HomologicalData::countDualCells ( unsigned dimension )

inline

Returns the number of cells of the given dimension in the dual CW-decomposition of the manifold.

This is typically much smaller than countStandardCells().

Parameters

dimension the dimension of the cells in question; this must be 0, 1, 2 or 3.

Returns: the number of cells of the given dimension in the dual CW-decomposition to the triangulation.

◆ countStandardCells()

unsigned long regina::HomologicalData::countStandardCells ( unsigned dimension )

inline

Returns the number of cells of the given dimension in the standard genuine CW-decomposition of the manifold.

In the case that the triangulation is a proper triangulation of a manifold (or delta-complex decomposition) it simply returns the same information as in the Triangulation<3> vertex, edge, face and tetrahedron lists.

In the case that this is an ideal triangulation, this algorithm returns the details of the corresponding compact manifold with boundary a union of closed surfaces.

Parameters

dimension the dimension of the cells in question; this must be 0, 1, 2 or 3.

Returns: the number of cells of the given dimension in the standard CW-decomposition of the closed manifold.

◆ detail()

std::string regina::Output< HomologicalData , supportsUtf8 >::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.

◆ dualHomology()

const MarkedAbelianGroup & regina::HomologicalData::dualHomology ( unsigned q )

This routine gives access to the manifold's homology computed with the dual CW-decomposition.

This routine is typically faster than homology() since the dual CW-decomposition generally has far fewer cells.

Note that the groups returned by homology() and dualHomology() are isomorphic, though they are generally described by different presentations.

Parameters

q	the dimension of the homology group: can be 0, 1, 2 or 3.

Returns: the q-th homology group, computed in the dual CW-decomposition.

◆ embeddabilityComment()

const std::string & regina::HomologicalData::embeddabilityComment ( )

inline

Returns a comment on whether the manifold might embed in a homology 3-sphere or 4-sphere.

Basically, this routine runs through all the Kawauchi-Kojima conditions, plus a few other ‘elementary’ conditions.

Each comment will be formatted as one or more English sentences (i.e., with capitalisation and punctuation). The comments themselves are subject to change between releases of Regina, since later releases may have more detailed tests at their disposal.

This routine is available for both orientable and non-orientable triangulations. In the non-orientable case it may return additional information regarding the orientable double cover.

Precondition: The triangulation is of a connected 3-manifold.

Warning: The code that computes the torsion linking form includes some floating-point arithmetic that could be subject to round-off error. Such errors are not expected, since this code is simply distinguishing different multiples of a known irrational; nevertheless, these results should at present be considered non-rigorous.

Exceptions

UnsolvedCase The torsion linking form could not be computed. This should be rare: the only way it can occur is during an internal rational-to-double conversion if the rational is out of range.

Returns: a string giving a one-line description of what is known about where this manifold embeds, based solely on the manifold's homological data.

◆ eulerChar()

long int regina::HomologicalData::eulerChar ( )

inline

The proper Euler characteristic of the manifold, computed from the dual CW-decomposition.

This routine calculates the Euler characteristic of the corresponding compact triangulated 3-manifold, with each ideal vertex treated as a surface boundary component.

This routine returns the same value as Triangulation<3>::eulerCharManifold(), though it computes it in a different way.

On the other hand, this routine differs from Triangulation<3>::eulerCharTri(), which handles ideal triangulations in a non-standard way (treating each ideal vertex as just a single vertex).

Returns: the Euler characteristic of the corresponding compact triangulated 3-manifold.

◆ formIsHyperbolic()

bool regina::HomologicalData::formIsHyperbolic ( )

Returns true iff torsion linking form is ‘hyperbolic’ in the linking-form sense of the word.

To be a little more precise, Poincare-duality in a compact orientable boundaryless manifold gives an isomorphism between the torsion subgroup of H_1(M) denoted tH_1(M) and Hom(tH_1(M),Q/Z), where Q is the rationals and Z the integers. The associated bilinear form (with values in Q/Z) is said to be ‘hyperbolic’ if tH_1(M) splits as a direct sum A+B such that Poincare duality sends A to Hom(B,Q/Z) and B to Hom(A,Q/Z).

Precondition: The triangulation is of a connected orientable 3-manifold.

Warning: The code that computes the torsion linking form includes some floating-point arithmetic that could be subject to round-off error. Such errors are not expected, since this code is simply distinguishing different multiples of a known irrational; nevertheless, these results should at present be considered non-rigorous.

Exceptions

UnsolvedCase The torsion linking form could not be computed. This should be rare: the only way it can occur is during an internal rational-to-double conversion if the rational is out of range.

Returns: true iff the torsion linking form is hyperbolic.

◆ formIsSplit()

bool regina::HomologicalData::formIsSplit ( )

inline

Returns true iff the torsion linking form is split.

Precondition: The triangulation is of a connected orientable 3-manifold.

Warning: The code that computes the torsion linking form includes some floating-point arithmetic that could be subject to round-off error. Such errors are not expected, since this code is simply distinguishing different multiples of a known irrational; nevertheless, these results should at present be considered non-rigorous.

Exceptions

UnsolvedCase The torsion linking form could not be computed. This should be rare: the only way it can occur is during an internal rational-to-double conversion if the rational is out of range.

Returns: true iff the linking form is split.

◆ formSatKK()

bool regina::HomologicalData::formSatKK ( )

inline

Returns true iff the torsion linking form satisfies the Kawauchi-Kojima 2-torsion condition.

This condition states that on all elements x of order 2^k, 2^{k-1}form(x,x) = 0.

This is a neccessary condition for an orientable 3-manifold perhaps with boundary to embed in a homology 4-sphere.

Precondition: The triangulation is of a connected orientable 3-manifold.

Warning: The code that computes the torsion linking form includes some floating-point arithmetic that could be subject to round-off error. Such errors are not expected, since this code is simply distinguishing different multiples of a known irrational; nevertheless, these results should at present be considered non-rigorous.

Exceptions

UnsolvedCase The torsion linking form could not be computed. This should be rare: the only way it can occur is during an internal rational-to-double conversion if the rational is out of range.

Returns: true iff the form satisfies the 2-torsion condition of Kawauchi-Kojima.

◆ h1CellAp()

const HomMarkedAbelianGroup & regina::HomologicalData::h1CellAp ( )

Returns the isomorphism from dualHomology(1) to homology(1) given by a cellular approximation to the identity map on the manifold.

Returns: The isomorphism from dualHomology(1) to homology(1) computed via a cellular approximation of the identity map from the first 1-skeleton to the second.

◆ homology()

const MarkedAbelianGroup & regina::HomologicalData::homology ( unsigned q )

This routine gives access to the manifold's homology computed with the regular CW-decomposition.

This routine is typically slower than dualHomology(), since dualHomology() uses the dual CW-decomposition which typically has an order of magnitude fewer cells.

Note that the groups returned by homology() and dualHomology() are isomorphic, though they are generally described by different presentations.

Parameters

q	the dimension of the homology group: can be 0, 1, 2 or 3.

Returns: the q-th homology group, computed in the standard CW-decomposition.

◆ operator=() [1/2]

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

default

Sets this to be a copy of the given object.

This operator induces a deep copy of the given object; moreover, this is expensive since HomologicalData objects are very large.

Returns: a reference to this normal surface.

◆ operator=() [2/2]

HomologicalData & regina::HomologicalData::operator= ( HomologicalData && )

defaultnoexcept

Moves the contents of the given object into this object.

This operation is constant time, but it is still expensive constant time because HomologicalData objects are very large.

The object that was passed will no longer be usable.

Returns: a reference to this object.

◆ str()

std::string regina::Output< HomologicalData , supportsUtf8 >::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.

◆ swap()

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

noexcept

Swaps the contents of this and the given object.

Warning: Although this operation is constant time, the HomologicalData class contains an enormous amount of data spread across many different member variables, and so this should really be considered "expensive constant time". You should still work to avoid swapping (or moving, and certainly copying) HomologicalData objects where possible.

Parameters

other the object whose contents should be swapped with this.

◆ torsionLegendreSymbolVector()

const std::vector< std::pair< Integer, std::vector< int > > > & regina::HomologicalData::torsionLegendreSymbolVector ( )

inline

Returns the odd p-torsion Legendre symbol vector.

This is the last of the three Kawauchi-Kojima invariants.

For details, see "Algebraic classification of linking pairings on 3-manifolds", Akio Kawauchi and Sadayoshi Kojima, Math. Ann. 253 (1980), 29–42.

Precondition: The triangulation is of a connected orientable 3-manifold.

Warning: The code that computes the torsion linking form includes some floating-point arithmetic that could be subject to round-off error. Such errors are not expected, since this code is simply distinguishing different multiples of a known irrational; nevertheless, these results should at present be considered non-rigorous.

Exceptions

UnsolvedCase The torsion linking form could not be computed. This should be rare: the only way it can occur is during an internal rational-to-double conversion if the rational is out of range.

Returns: the Legendre symbol vector associated to the torsion linking form.

◆ torsionLegendreSymbolVectorString()

const std::string & regina::HomologicalData::torsionLegendreSymbolVectorString ( )

inline

Same as torsionLegendreSymbolVector() but returns as a human-readable string.

Precondition: The triangulation is of a connected orientable 3-manifold.

Warning: The code that computes the torsion linking form includes some floating-point arithmetic that could be subject to round-off error. Such errors are not expected, since this code is simply distinguishing different multiples of a known irrational; nevertheless, these results should at present be considered non-rigorous.

Exceptions

UnsolvedCase The torsion linking form could not be computed. This should be rare: the only way it can occur is during an internal rational-to-double conversion if the rational is out of range.

Returns: the Legendre symbol vector in human-readable form.

◆ torsionRankVector()

const std::vector< std::pair< Integer, std::vector< unsigned long > > > & regina::HomologicalData::torsionRankVector ( )

inline

Returns the torsion form rank vector.

This is the first of the three Kawauchi-Kojima complete invariants of the torsion linking form.

This vector describes the rank of the torsion subgroup of H1, given in prime power form. It is a vector of pairs (p, x), where p is a prime and x is its exponent.

For details, see "Algebraic classification of linking pairings on 3-manifolds", Akio Kawauchi and Sadayoshi Kojima, Math. Ann. 253 (1980), 29–42.

Precondition: The triangulation is of a connected orientable 3-manifold.

Warning: The code that computes the torsion linking form includes some floating-point arithmetic that could be subject to round-off error. Such errors are not expected, since this code is simply distinguishing different multiples of a known irrational; nevertheless, these results should at present be considered non-rigorous.

Exceptions

UnsolvedCase The torsion linking form could not be computed. This should be rare: the only way it can occur is during an internal rational-to-double conversion if the rational is out of range.

Returns: the torsion form rank vector.

◆ torsionRankVectorString()

const std::string & regina::HomologicalData::torsionRankVectorString ( )

inline

Same as torsionRankVector() but returns as a human-readable string.

Precondition: The triangulation is of a connected orientable 3-manifold.

Warning: The code that computes the torsion linking form includes some floating-point arithmetic that could be subject to round-off error. Such errors are not expected, since this code is simply distinguishing different multiples of a known irrational; nevertheless, these results should at present be considered non-rigorous.

Exceptions

UnsolvedCase The torsion linking form could not be computed. This should be rare: the only way it can occur is during an internal rational-to-double conversion if the rational is out of range.

Returns: human-readable prime power factorization of the order of the torsion subgroup of H1.

◆ torsionSigmaVector()

const std::vector< LargeInteger > & regina::HomologicalData::torsionSigmaVector ( )

inline

Returns the 2-torsion sigma vector.

This is the second of the three Kawauchi-Kojima invariants. It is orientation-sensitive.

For details, see "Algebraic classification of linking pairings on 3-manifolds", Akio Kawauchi and Sadayoshi Kojima, Math. Ann. 253 (1980), 29–42.

Precondition: The triangulation is of a connected orientable 3-manifold.

Warning: The code that computes the torsion linking form includes some floating-point arithmetic that could be subject to round-off error. Such errors are not expected, since this code is simply distinguishing different multiples of a known irrational; nevertheless, these results should at present be considered non-rigorous.

Exceptions

UnsolvedCase The torsion linking form could not be computed. This should be rare: the only way it can occur is during an internal rational-to-double conversion if the rational is out of range.

Returns: the Kawauchi-Kojima sigma-vector.

◆ torsionSigmaVectorString()

const std::string & regina::HomologicalData::torsionSigmaVectorString ( )

inline

Same as torsionSigmaVector() but returns as a human-readable string.

This is an orientation-sensitive invariant.

Precondition: The triangulation is of a connected orientable 3-manifold.

Warning: The code that computes the torsion linking form includes some floating-point arithmetic that could be subject to round-off error. Such errors are not expected, since this code is simply distinguishing different multiples of a known irrational; nevertheless, these results should at present be considered non-rigorous.

Exceptions

UnsolvedCase The torsion linking form could not be computed. This should be rare: the only way it can occur is during an internal rational-to-double conversion if the rational is out of range.

Returns: the Kawauchi-Kojima sigma-vector in human readable form.

◆ utf8()

std::string regina::Output< HomologicalData , supportsUtf8 >::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.

◆ writeTextLong()

void regina::ShortOutput< HomologicalData , false >::writeTextLong ( std::ostream & out ) const

inlineinherited

A default implementation for detailed output.

This routine simply calls T::writeTextShort() and appends a final newline.

Python: Not present. Instead you can call detail() from the subclass T, which returns this output as a string.

Parameters

out	the output stream to which to write.

◆ writeTextShort()

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

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

Note this only writes pre-computed data. Thus if you have not yet asked HomologicalData to compute anything about this triangulation, writeTextShort may be empty.

Python: Not present. Use str() instead.

Parameters

out	the output stream to which to write.

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

triangulation/dim3/homologicaldata.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ HomologicalData() [1/3]

◆ HomologicalData() [2/3]

◆ HomologicalData() [3/3]

Member Function Documentation

◆ bdryHomology()

◆ bdryHomologyMap()

◆ countBdryCells()

◆ countDualCells()

◆ countStandardCells()

◆ detail()

◆ dualHomology()

◆ embeddabilityComment()

◆ eulerChar()

◆ formIsHyperbolic()

◆ formIsSplit()

◆ formSatKK()

◆ h1CellAp()

◆ homology()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ str()

◆ swap()

◆ torsionLegendreSymbolVector()

◆ torsionLegendreSymbolVectorString()

◆ torsionRankVector()

◆ torsionRankVectorString()

◆ torsionSigmaVector()

◆ torsionSigmaVectorString()

◆ utf8()

◆ writeTextLong()

◆ writeTextShort()