Represents an angle structure on a triangulation. More...

#include <angle/anglestructure.h>

Inheritance diagram for regina::AngleStructure:

Public Member Functions
	AngleStructure (const AngleStructure &)=default
	Creates a new copy of the given angle structure. More...

	AngleStructure (const AngleStructure &src, const Triangulation< 3 > &triangulation)
	Creates a new copy of the given angle structure, but relocated to the given triangulation. More...

	AngleStructure (const AngleStructure &src, const SnapshotRef< Triangulation< 3 > > &triangulation)
	Creates a new copy of the given angle structure, but relocated to the given triangulation. More...

	AngleStructure (AngleStructure &&) noexcept=default
	Moves the given angle structure into this new angle structure. More...

	AngleStructure (const Triangulation< 3 > &triang, const Vector< Integer > &vector)
	Creates a new angle structure on the given triangulation with the given coordinate vector. More...

	AngleStructure (const Triangulation< 3 > &triang, Vector< Integer > &&vector)
	Creates a new angle structure on the given triangulation with the given coordinate vector. More...

	AngleStructure (const SnapshotRef< Triangulation< 3 > > &triang, const Vector< Integer > &vector)
	Creates a new angle structure on the given triangulation with the given coordinate vector. More...

	AngleStructure (const SnapshotRef< Triangulation< 3 > > &triang, Vector< Integer > &&vector)
	Creates a new angle structure on the given triangulation with the given coordinate vector. More...

AngleStructure &	operator= (const AngleStructure &)=default
	Sets this to be a copy of the given angle structure. More...

AngleStructure &	operator= (AngleStructure &&) noexcept=default
	Moves the contents of the given angle structure to this structure. More...

void	swap (AngleStructure &other) noexcept
	Swaps the contents of this and the given angle structure. More...

Rational	angle (size_t tetIndex, int edgePair) const
	Returns the requested angle in this angle structure. More...

const Triangulation< 3 > &	triangulation () const
	Returns the triangulation on which this angle structure lies. More...

bool	isStrict () const
	Determines whether this is a strict angle structure. More...

bool	isTaut () const
	Determines whether this is a taut angle structure. More...

bool	isVeering () const
	Determines whether this is a veering structure. More...

const Vector< Integer > &	vector () const
	Gives read-only access to the integer vector that Regina uses internally to represent this angle structure. More...

bool	operator== (const AngleStructure &other) const
	Determines whether this and the given angle structure are identical. More...

bool	operator!= (const AngleStructure &other) const
	Determines whether this and the given angle structure are different. More...

bool	operator< (const AngleStructure &other) const
	Imposes a total order on all angle structures. More...

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

void	writeXMLData (std::ostream &out) const
	Writes a chunk of XML containing this angle structure and all of its properties. 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...

Protected Member Functions
void	calculateType () const
	Calculates the structure type (strict or taut) and stores it as a property. More...

Friends
class	regina::XMLAngleStructureReader

Detailed Description

Represents an angle structure on a triangulation.

Since Regina 7.0, you can modify or even destroy the original triangulation that was used to create this angle structure. If you do, then this angle structure will automatically make a private copy of the original triangulation as an ongoing reference. Different angle structures (and normal surfaces) can all share the same private copy, so this is not an expensive process.

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.

Constructor & Destructor Documentation

◆ AngleStructure() [1/8]

regina::AngleStructure::AngleStructure ( const AngleStructure & )

default

Creates a new copy of the given angle structure.

◆ AngleStructure() [2/8]

regina::AngleStructure::AngleStructure	(	const AngleStructure &	src,
		const Triangulation< 3 > &	triangulation
	)

inline

Creates a new copy of the given angle structure, but relocated to the given triangulation.

A snapshot will be taken of the given triangulation as it appears right now. You may change or even delete the triangulation later on; if so, then this angle structure will still refer to the frozen snapshot that was taken at the time of construction.

Precondition: The given triangulation is either the same as, or is combinatorially identical to, the triangulation on which src is placed.

Parameters

src	the angle structure to copy.
triangulation	the triangulation on which this new angle structure will be placed.

◆ AngleStructure() [3/8]

regina::AngleStructure::AngleStructure	(	const AngleStructure &	src,
		const SnapshotRef< Triangulation< 3 > > &	triangulation
	)

inline

Creates a new copy of the given angle structure, but relocated to the given triangulation.

Precondition: The given triangulation is either the same as, or is combinatorially identical to, the triangulation on which src is placed.

Python: Not present. Instead use the version that takes a "pure" triangulation.

Parameters

src	the angle structure to copy.
triangulation	a snapshot, frozen in time, of the triangulation on which this new angle structure will be placed.

◆ AngleStructure() [4/8]

regina::AngleStructure::AngleStructure ( AngleStructure && )

defaultnoexcept

Moves the given angle structure into this new angle structure.

This is a fast (constant time) operation.

The angle structure that is passed will no longer be usable.

◆ AngleStructure() [5/8]

regina::AngleStructure::AngleStructure	(	const Triangulation< 3 > &	triang,
		const Vector< Integer > &	vector
	)

inline

Creates a new angle structure on the given triangulation with the given coordinate vector.

A snapshot will be taken of the given triangulation as it appears right now. You may change or even delete the triangulation later on; if so, then this angle structure will still refer to the frozen snapshot that was taken at the time of construction.

Precondition: The given coordinate vector represents an angle structure on the given triangulation, according to the integer vector representation described in the notes for vector().

Python: Instead of a Vector<Integer>, you may (if you prefer) pass a Python list of integers.

Parameters

triang	the triangulation on which this angle structure lies.
vector	a vector containing the individual angles in the angle structure.

◆ AngleStructure() [6/8]

regina::AngleStructure::AngleStructure	(	const Triangulation< 3 > &	triang,
		Vector< Integer > &&	vector
	)

inline

Creates a new angle structure on the given triangulation with the given coordinate vector.

A snapshot will be taken of the given triangulation as it appears right now. You may change or even delete the triangulation later on; if so, then this angle structure will still refer to the frozen snapshot that was taken at the time of construction.

Precondition: The given coordinate vector represents an angle structure on the given triangulation, according to the integer vector representation described in the notes for vector().

Python: Not present. Instead use the version that copies vector.

Parameters

triang	the triangulation on which this angle structure lies.
vector	a vector containing the individual angles in the angle structure.

◆ AngleStructure() [7/8]

regina::AngleStructure::AngleStructure	(	const SnapshotRef< Triangulation< 3 > > &	triang,
		const Vector< Integer > &	vector
	)

inline

Creates a new angle structure on the given triangulation with the given coordinate vector.

Precondition: The given coordinate vector represents an angle structure on the given triangulation, according to the integer vector representation described in the notes for vector().

Python: Not present. Instead use the version that takes a "pure" triangulation.

Parameters

triang	a snapshot, frozen in time, of the triangulation on which this angle structure lies.
vector	a vector containing the individual angles in the angle structure.

◆ AngleStructure() [8/8]

regina::AngleStructure::AngleStructure	(	const SnapshotRef< Triangulation< 3 > > &	triang,
		Vector< Integer > &&	vector
	)

inline

Creates a new angle structure on the given triangulation with the given coordinate vector.

Precondition: The given coordinate vector represents an angle structure on the given triangulation, according to the integer vector representation described in the notes for vector().

Python: Not present. Instead use the version that takes a "pure" triangulation and copies vector.

Parameters

triang	a snapshot, frozen in time, of the triangulation on which this angle structure lies.
vector	a vector containing the individual angles in the angle structure.

Member Function Documentation

◆ angle()

Rational regina::AngleStructure::angle	(	size_t	tetIndex,
		int	edgePair
	)		const

Returns the requested angle in this angle structure.

The angle returned will be scaled down; the actual angle is the returned value multiplied by π.

Within a tetrahedron, the three angles are indexed 0, 1 and 2. Angle i appears on edge i of the tetrahedron as well as its opposite edge (5-i).

Parameters

tetIndex	the index in the triangulation of the tetrahedron in which the requested angle lives; this should be between 0 and Triangulation<3>::size()-1 inclusive.
edgePair	the number representing the pair of edges holding the requested angle, as described above; this should be 0, 1 or 2.

Returns: the requested angle scaled down by π.

◆ calculateType()

void regina::AngleStructure::calculateType ( ) const

protected

Calculates the structure type (strict or taut) and stores it as a property.

◆ detail()

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

◆ isStrict()

bool regina::AngleStructure::isStrict ( ) const

inline

Determines whether this is a strict angle structure.

A strict angle structure has all angles strictly between (not including) 0 and π.

Returns: true if and only if this is a strict angle structure.

◆ isTaut()

bool regina::AngleStructure::isTaut ( ) const

inline

Determines whether this is a taut angle structure.

A taut angle structure contains only angles 0 and π.

Here we use the Kang-Rubinstein definition of a taut angle structure [1], which is based on the angles alone. In his original paper [2], Lackenby has an extra condition whereby 2-faces of the triangulation must have consistent coorientations, which we do not enforce here.

[1] E. Kang and J. H. Rubinstein, "Ideal triangulations of 3-manifolds II; Taut and angle structures", Algebr. Geom. Topol. 5 (2005), pp. 1505-1533.

[2] M. Lackenby, "Taut ideal triangulations of 3-manifolds", Geom. Topol. 4 (2000), pp. 369-395.

Returns: true if and only if this is a taut structure.

◆ isVeering()

bool regina::AngleStructure::isVeering ( ) const

inline

Determines whether this is a veering structure.

A veering structure is taut angle structure with additional strong combinatorial constraints, which we do not outline here. For a definition, see C. D. Hodgson, J. H. Rubinstein, H. Segerman, and S. Tillmann, "Veering triangulations admit strict angle structures", Geom. Topol., 15 (2011), pp. 2073-2089.

Note that the Hodgson et al. definition is slightly more general than Agol's veering taut triangulations from his original paper: I. Agol, " Ideal triangulations of pseudo-Anosov mapping tori", in "Topology and Geometry in Dimension Three", volume 560 of Contemp. Math., pp. 1-17, Amer. Math. Soc., 2011. This mirrors the way in which the Kang-Rubinstein definition of taut angle structure is slightly more general than Lackenby's. See the Hodgson et al. paper for full details and comparisons between the two settings.

If this angle structure is not taut, or if the underlying triangulation is non-orientable, then this routine will return false.

Returns: true if and only if this is a veering structure.

◆ operator!=()

bool regina::AngleStructure::operator!= ( const AngleStructure & other ) const

inline

Determines whether this and the given angle structure are different.

This routine is safe to call even if this and the given angle structure do not belong to the same triangulation:

If the two triangulations have the same size, then this routine will test whether this angle structure, if transplanted into the other triangulation using the same tetrahedron numbering, would be different from other.
If the two triangulations have different sizes, then this routine will return true.

Parameters

other the angle structure to be compared with this structure.

Returns: true if and only if this and the given structure are different.

◆ operator<()

bool regina::AngleStructure::operator< ( const AngleStructure & other ) const

Imposes a total order on all angle structures.

This order is not mathematically meaningful; it is merely provided for scenarios where you need to be able to sort angle structures (e.g., when using them as keys in a map).

The order is well-defined, and will be preserved across copy/move operations, different program executions, and different platforms (since it is defined purely in terms of the angle coordinates, and does not use transient properties such as locations in memory).

This operation is consistent with the equality test. In particular, it does not matter whether the two angle structures belong to different triangulations. See the equality test operator==() for further details.

Parameters

other the angle structure to be compared with this structure.

Returns: true if and only if this appears before the given structure in the total order.

◆ operator=() [1/2]

AngleStructure & regina::AngleStructure::operator= ( AngleStructure && )

defaultnoexcept

Moves the contents of the given angle structure to this structure.

This is a fast (constant time) operation.

This and the given angle structure do not need to be on the same underlying triangulation, and they do not need to have the same length vectors (but of course if either property differs then this structure will be adjusted accordingly).

The structure that was passed will no longer be usable.

Returns: a reference to this angle structure.

◆ operator=() [2/2]

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

default

Sets this to be a copy of the given angle structure.

This and the given angle structure do not need to be on the same underlying triangulation, and they do not need to have the same length vectors (but of course if either property differs then this structure will be adjusted accordingly).

This operator induces a deep copy of the given angle structure.

Returns: a reference to this angle structure.

◆ operator==()

bool regina::AngleStructure::operator== ( const AngleStructure & other ) const

inline

Determines whether this and the given angle structure are identical.

This routine is safe to call even if this and the given angle structure do not belong to the same triangulation:

If the two triangulations have the same size, then this routine will test whether this angle structure, if transplanted into the other triangulation using the same tetrahedron numbering, would be the same as other.
If the two triangulations have different sizes, then this routine will return false.

Parameters

other the angle structure to be compared with this structure.

Returns: true if and only if this and the given structure are identical.

◆ str()

std::string regina::Output< AngleStructure , 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::AngleStructure::swap ( AngleStructure & other )

inlinenoexcept

Swaps the contents of this and the given angle structure.

This is a fast (constant time) operation.

This and the given angle structure do not need to be on the same underlying triangulation, and they do not need to have the same length vectors (but of course if either property differs then these features will be adjusted accordingly).

Parameters

other the angle structure whose contents should be swapped with this.

◆ triangulation()

const Triangulation< 3 > & regina::AngleStructure::triangulation ( ) const

inline

Returns the triangulation on which this angle structure lies.

This will be a snapshot frozen in time of the triangulation that was originally passed to the AngleStructure constructor.

This will return a correct result even if the original triangulation has since been modified or destroyed. However, in order to ensure this behaviour, it is possible that at different points in time this function may return references to different C++ objects.

The rules for using the triangulation() reference are:

Do not keep the resulting reference as a long-term reference or pointer of your own, since in time you may find yourself referring to the wrong object (see above). Just call this function again.
You must respect the read-only nature of the result (i.e., you must not cast the constness away). The snapshotting process detects modifications, and modifying the frozen snapshot may result in an exception being thrown.

Returns: a reference to the underlying triangulation.

◆ utf8()

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

◆ vector()

const Vector< Integer > & regina::AngleStructure::vector ( ) const

inline

Gives read-only access to the integer vector that Regina uses internally to represent this angle structure.

This vector contains one member per angle plus a final scaling member; to obtain the actual angle in the angle structure one should divide the corresonding angle member by the scaling member and then multiply by π.

If there are t tetrahedra in the underlying triangulation, there will be precisely 3t+1 elements in this vector. The first three elements will be the angle members for the first tetrahedron, the next three for the second tetrahedron and so on. For each tetrahedron, the three individual elements are the angle members corresponding to edges 0, 1 and 2 of the tetrahedron (and also their opposite edges 5, 4 and 3 respectively). The final element of the vector is the scaling member as described above.

Returns: the underlying integer vector.

◆ writeTextLong()

void regina::ShortOutput< AngleStructure , 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::AngleStructure::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 output stream to which to write.

◆ writeXMLData()

void regina::AngleStructure::writeXMLData ( std::ostream & out ) const

Writes a chunk of XML containing this angle structure and all of its properties.

This routine will be called from within AngleStructures::writeXMLPacketData().

Python: The argument out should be an open Python file object.

Parameters

out	the output stream to which the XML should be written.

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

angle/anglestructure.h

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ AngleStructure() [1/8]

◆ AngleStructure() [2/8]

◆ AngleStructure() [3/8]

◆ AngleStructure() [4/8]

◆ AngleStructure() [5/8]

◆ AngleStructure() [6/8]

◆ AngleStructure() [7/8]

◆ AngleStructure() [8/8]

Member Function Documentation

◆ angle()

◆ calculateType()

◆ detail()

◆ isStrict()

◆ isTaut()

◆ isVeering()

◆ operator!=()

◆ operator<()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ str()

◆ swap()

◆ triangulation()

◆ utf8()

◆ vector()

◆ writeTextLong()

◆ writeTextShort()

◆ writeXMLData()