A collection of angle structures on a 3-manifold triangulation. More...

#include <angle/anglestructures.h>

Inheritance diagram for regina::AngleStructures:

Public Member Functions
	AngleStructures (const Triangulation< 3 > &triangulation, bool tautOnly=false, AngleAlg algHints=AS_ALG_DEFAULT, ProgressTracker *tracker=nullptr)
	A unified constructor for enumerating various classes of angle structures on a given triangulation. More...

	AngleStructures (const AngleStructures &)=default
	Constructs a new copy of the given list. More...

	AngleStructures (AngleStructures &&src) noexcept=default
	Moves the given list into this new list. More...

AngleStructures &	operator= (const AngleStructures &src)
	Sets this to be a (deep) copy of the given list. More...

AngleStructures &	operator= (AngleStructures &&src)
	Moves the contents of the given list into this list. More...

void	swap (AngleStructures &other)
	Swaps the contents of this and the given list. More...

const Triangulation< 3 > &	triangulation () const
	Returns the triangulation on which these angle structures lie. More...

bool	isTautOnly () const
	Returns whether this list was produced by enumerating taut angle structures only. More...

AngleAlg	algorithm () const
	Returns details of the algorithm that was used to enumerate this list. More...

size_t	size () const
	Returns the number of angle structures stored in this list. More...

const AngleStructure &	structure (size_t index) const
	Returns the angle structure at the requested index in this list. More...

auto	begin () const
	Returns an iterator at the beginning of this list of angle structures. More...

auto	end () const
	Returns an iterator beyond the end of this list of angle structures. More...

bool	spansStrict () const
	Determines whether any convex combination of the angle structures in this list is a strict angle structure. More...

bool	spansTaut () const
	Determines whether any angle structure in this list is a taut structure. More...

bool	operator== (const AngleStructures &other) const
	Determines whether this and the given list contain the same set of angle structures. More...

bool	operator!= (const AngleStructures &other) const
	Determines whether this and the given list contain different sets of angle structures. 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...

std::shared_ptr< PacketOf< AngleStructures > >	packet ()
	Returns the packet that holds this data, if there is one. More...

std::shared_ptr< const PacketOf< AngleStructures > >	packet () const
	Returns the packet that holds this data, if there is one. More...

std::string	anonID () const
	A unique string ID that can be used in place of a packet ID. 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...

Static Public Member Functions
static std::shared_ptr< PacketOf< AngleStructures > >	enumerate (Triangulation< 3 > &owner, bool tautOnly=false, ProgressTracker *tracker=nullptr)
	Deprecated routine to enumerate angle structures on a given triangulation. More...

static std::shared_ptr< PacketOf< AngleStructures > >	enumerateTautDD (Triangulation< 3 > &owner)
	Deprecated routine to enumerate all taut angle structures on the given triangulation using the double description method. More...

Protected Member Functions
	AngleStructures (bool tautOnly, AngleAlg algHints, const Triangulation< 3 > &triangulation)
	Creates a new empty angle structure list. More...

void	calculateSpanStrict () const
	Calculate whether the convex span of this list includes a strict angle structure. More...

void	calculateSpanTaut () const
	Calculate whether the convex span of this list includes a taut structure. More...

Protected Attributes
PacketHeldBy	heldBy_
	Indicates whether this Held object is in fact the inherited data for a PacketOf<Held>. More...

Friends
class	regina::XMLAngleStructuresReader

class	regina::XMLLegacyAngleStructuresReader

class	regina::XMLWriter< AngleStructures >

Detailed Description

A collection of angle structures on a 3-manifold triangulation.

There are some important changes to this class as of Regina 7.0:

An angle structure list does not need to be a child packet of the underlying triangulation, and indeed does not need to interact with the packet tree at all.
You are welcome to modify or even destroy the original triangulation; if you do then this list will automatically make a private copy of the original triangulation as an ongoing reference. Different angle structure lists (and normal surface lists) can all share the same private copy, so this is not an expensive process.
You should now create angle structure lists using the class constructor (but which, unlike the old enumerate(), does not insert the list into the packet tree). There is no need to use enumerate() any more.

Since Regina 7.0, this is no longer a "packet type" that can be inserted directly into the packet tree. Instead an angle structure list is now a standalone mathematatical object, which makes it slimmer and faster for ad-hoc use. The consequences of this are:

If you create your own AngleStructures object, it will not have any of the usual packet infrastructure. You cannot add it into the packet tree, and it will not support a label, tags, child/parent packets, and/or event listeners.
To include an AngleStructures object in the packet tree, you must create a new PacketOf<AngleStructures>. This is a packet type, and supports labels, tags, child/parent packets, and event listeners. It derives from AngleStructures, and so inherits the full AngleStructures interface.
If you are adding new functions to this class that edit the list, you must still remember to create a ChangeEventSpan. This will ensure that, if the list is being managed by a PacketOf<AngleStructures>, then the appropriate packet change events will be fired. All other events (aside from packetToBeChanged() and packetWasChanged() are managed directly by the PacketOf<AngleStructures> wrapper class.

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

◆ AngleStructures() [1/4]

regina::AngleStructures::AngleStructures	(	const Triangulation< 3 > &	triangulation,
		bool	tautOnly = `false`,
		AngleAlg	algHints = `AS_ALG_DEFAULT`,
		ProgressTracker *	tracker = `nullptr`
	)

inline

A unified constructor for enumerating various classes of angle structures on a given triangulation.

If tautOnly is false (the default), then this new list will be filled with all vertices of the angle structure solution space. If tautOnly is true, then the list will be filled with only the taut angle structures (a subset of the vertex angle structures); these are usually much faster to enumerate.

The AngleAlg argument is a combination of flags that allows you to control the underlying enumeration algorithm. These flags are treated as hints only: if your selection of algorithm is invalid, unavailable or unsupported then Regina will choose something more appropriate. Unless you have some specialised need, the default AS_ALG_DEFAULT (which makes no hints at all) will allow Regina to choose what it thinks will be the most efficient method.

Unlike the old enumerate() function, the new angle structure list will not be inserted into the packet tree. Moreover, the given triangulation may change or even be destroyed without causing problems. See the class notes for details.

If a progress tracker is passed, this routine will declare and work through a series of stages whose combined weights sum to 1; typically this means that the given tracker must not have been used before.

This constructor will not return until the enumeration of angle structures is complete, regardless of whether a progress tracker was passed. If you need the behaviour of the old enumerate() (where passing a progress tracker caused the enumeration to start in the background), simply call this constructor in a new detached thread. Note that this enumeration can be extremely slow for larger triangulations, and so there could be good reasons to do this.

Python: The global interpreter lock will be released while this constructor runs, so you can use it with Python-based multithreading.

Parameters

triangulation	the triangulation for which the vertex angle structures will be enumerated.
tautOnly	`true` if only taut structures are to be enuemrated, or `false` if we should enumerate all vertices of the angle structure solution space.
algHints	passes requests to Regina for which specific enumeration algorithm should be used.
tracker	a progress tracker through which progress will be reported, or `null` if no progress reporting is required.

◆ AngleStructures() [2/4]

regina::AngleStructures::AngleStructures ( const AngleStructures & )

default

Constructs a new copy of the given list.

◆ AngleStructures() [3/4]

regina::AngleStructures::AngleStructures ( AngleStructures && src )

defaultnoexcept

Moves the given list into this new list.

This is a fast (constant time) operation.

The list that is passed will no longer be usable.

Note: This operator is marked noexcept, and in particular does not fire any change events. This is because this list is freshly constructed (and therefore has no listeners yet), and because we assume that src is about to be destroyed (an action that will fire a packet destruction event).

Parameters

src	the list to move.

◆ AngleStructures() [4/4]

regina::AngleStructures::AngleStructures	(	bool	tautOnly,
		AngleAlg	algHints,
		const Triangulation< 3 > &	triangulation
	)

inlineprotected

Creates a new empty angle structure list.

All properties are marked as unknown.

Parameters

tautOnly	`true` if only taut structures are to be enuemrated (when the time comes for enumeration to be performed), or `false` if we should enumerate all vertices of the angle structure solution space.
algHints	contains requests for which specific enumeration algorithm should be used.
triangulation	the triangulation on which the angle structures will lie.

Member Function Documentation

◆ algorithm()

AngleAlg regina::AngleStructures::algorithm ( ) const

inline

Returns details of the algorithm that was used to enumerate this list.

These may not be the same AngleAlg flags that were passed to the class constructor. In particular, default values will have been explicitly filled in, invalid and/or redundant values will have been removed, and unavailable and/or unsupported combinations of algorithm flags will be replaced with whatever algorithm was actually used.

Returns: details of the algorithm used to enumerate this list.

◆ anonID()

std::string regina::PacketData< AngleStructures >::anonID

inherited

A unique string ID that can be used in place of a packet ID.

This is an alternative to Packet::internalID(), and is designed for use when Held is not actually wrapped by a PacketOf<Held>. (An example of such a scenario is when a normal surface list needs to write its triangulation to file, but the triangulation is a standalone object that is not stored in a packet.)

The ID that is returned will:

remain fixed throughout the lifetime of the program for a given object, even if the contents of the object are changed;
not clash with the anonID() returned from any other object, or with the internalID() returned from any packet of any type;

These IDs are not preserved when copying or moving one object to another, and are not preserved when writing to a Regina data file and then reloading the file contents.

Warning: If this object is wrapped in a PacketOf<Held>, then anonID() and Packet::internalID() may return different values.

See Packet::internalID() for further details.

Returns: a unique ID that identifies this object.

◆ begin()

auto regina::AngleStructures::begin ( ) const

inline

Returns an iterator at the beginning of this list of angle structures.

The begin() and end() functions allow you to iterate through all angle structures in this list using C++11 range-based for loops:

AngleStructures list(...);

for (const AngleStructure& s : list) { ... }

regina::AngleStructures::AngleStructures

AngleStructures(const Triangulation< 3 > &triangulation, bool tautOnly=false, AngleAlg algHints=AS_ALG_DEFAULT, ProgressTracker *tracker=nullptr)

A unified constructor for enumerating various classes of angle structures on a given triangulation.

Definition: anglestructures.h:636

In Python, an angle structure list can be treated as an iterable object:

list = AngleStructures(...)
for s in list:
    ...

The type that is returned will be a lightweight iterator type, guaranteed to satisfy the C++ LegacyRandomAccessIterator requirement. The precise C++ type of the iterator is subject to change, so C++ users should use auto (just like this declaration does).

Returns: an iterator at the beginning of this list.

◆ calculateSpanStrict()

void regina::AngleStructures::calculateSpanStrict ( ) const

protected

Calculate whether the convex span of this list includes a strict angle structure.

◆ calculateSpanTaut()

void regina::AngleStructures::calculateSpanTaut ( ) const

protected

Calculate whether the convex span of this list includes a taut structure.

◆ detail()

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

◆ end()

auto regina::AngleStructures::end ( ) const

inline

Returns an iterator beyond the end of this list of angle structures.

In C++, the begin() and end() routines allow you to iterate through all angle structures in this list using C++11 range-based for loops. In Python, an angle structure list can be treated as an iterable object.

See the begin() documentation for further details.

Returns: an iterator beyond the end of this list.

◆ enumerate()

static std::shared_ptr< PacketOf< AngleStructures > > regina::AngleStructures::enumerate	(	Triangulation< 3 > &	owner,
		bool	tautOnly = `false`,
		ProgressTracker *	tracker = `nullptr`
	)

static

Deprecated routine to enumerate angle structures on a given triangulation.

This static routine is identical to calling the class constructor with the given arguments, but with two differences:

If a progress tracker is passed, this routine will start the enumeration in a detached background thread and return immediately (unlike the class constructor, which does not return until the enumeration is finished).
This routine wraps the new angle structure list in a packet and inserts it beneath owner in the packet tree (unlike the class constructor, which creates a plain AngleStructures object). If a progress tracker is passed (i.e., the enumeration runs in a background thread) then this tree insertion will not happen until the enumeration has finished, and if the user cancels the operation then the insertion will not happen at all.

This function is safe to use even if owner is a "pure" Triangulation<3> or SnapPeaTriangulation, not a packet type. In such a scenario, this routine will still build the angle structure list, but the resulting packet will be orphaned.

See the class constructor for details on how this routine works and what the various arguments mean.

Deprecated:: Just call the AngleStructures constructor.

Python: For this deprecated function, the progress tracker argument is omitted. It is still possible to enumerate in the background with a progress tracker, but for that you will need to call the class constructor instead and create the new thread yourself.

Parameters

owner	the triangulation for which the vertex angle structures will be enumerated.
tautOnly	`true` if only taut structures are to be enuemrated, or `false` if we should enumerate all vertices of the angle structure solution space; this defaults to `false`.
tracker	a progress tracker through which progress will be reported, or `null` if no progress reporting is required.

Returns: the new angle structure list.

◆ enumerateTautDD()

static std::shared_ptr< PacketOf< AngleStructures > > regina::AngleStructures::enumerateTautDD ( Triangulation< 3 > & owner )

static

Deprecated routine to enumerate all taut angle structures on the given triangulation using the double description method.

This static routine is almost identical to calling the class constructor with the tautOnly argument set to true and the algHints argument set to AS_ALG_DD. The only difference is that, unlike the class constructor, this routine will also wrap the new angle structure list in a packet and insert it beneath owner in the packet tree.

This function is safe to use even if owner is a "pure" Triangulation<3> or SnapPeaTriangulation, not a packet type. In such a scenario, this routine will still build the angle structure list, but the resulting packet will be orphaned.

Note that default algorithm used by the class constructor for taut angle structures is the tree traversal method, which is based on linear programming, and which is typically much faster than the double description method for larger triangulations.

Warning: This routine is slow, and users will not want to call it unless they have some specialised need.

Deprecated:: Just call the AngleStructures constructor.

Parameters

owner the triangulation for which the taut angle structures will be enumerated.

Returns: the new angle structure list.

◆ isTautOnly()

bool regina::AngleStructures::isTautOnly ( ) const

inline

Returns whether this list was produced by enumerating taut angle structures only.

Returns: true if this list was produced by enumerating taut angle structures only, or false if the enumeration procedure allowed for any angle structures.

◆ operator!=()

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

inline

Determines whether this and the given list contain different sets of angle structures.

The lists will be compared as multisets: the order of the angle structures in each list does not matter; however, in the unusual scenario where a list the same angle structure multiple times, multiplicity does matter.

Like the comparison operators for AngleStructure, it does not matter whether the two lists work with different triangulations:

If the two triangulations have the same size, then this routine will compare angle structures as though they were transplanted into the same triangulation using the same tetrahedron numbering and the same angle coordinates.
If the two triangulations have different sizes, then this comparison will return true (i.e., the lists will be considered different).

Parameters

other the list to be compared with this list.

Returns: true if both lists do not represent the same multiset of angle structures, or false if they do.

◆ operator=() [1/2]

AngleStructures & regina::AngleStructures::operator= ( AngleStructures && src )

inline

Moves the contents of the given list into this list.

This is a fast (constant time) operation.

The list that is passed (src) will no longer be usable.

Note: This operator is not marked noexcept, since it fires change events on this list which may in turn call arbitrary code via any registered packet listeners. It deliberately does not fire change events on src, since it assumes that src is about to be destroyed (which will fire a destruction event instead).

Parameters

src	the list to move.

Returns: a reference to this list.

◆ operator=() [2/2]

AngleStructures & regina::AngleStructures::operator= ( const AngleStructures & src )

inline

Sets this to be a (deep) copy of the given list.

Parameters

src	the list to copy.

Returns: a reference to this list.

◆ operator==()

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

Determines whether this and the given list contain the same set of angle structures.

The lists will be compared as multisets: the order of the angle structures in each list does not matter; however, in the unusual scenario where a list the same angle structure multiple times, multiplicity does matter.

Like the comparison operators for AngleStructure, it does not matter whether the two lists work with different triangulations:

If the two triangulations have the same size, then this routine will compare angle structures as though they were transplanted into the same triangulation using the same tetrahedron numbering and the same angle coordinates.
If the two triangulations have different sizes, then this comparison will return false.

Parameters

other the list to be compared with this list.

Returns: true if both lists represent the same multiset of angle structures, or false if not.

◆ packet() [1/2]

std::shared_ptr< PacketOf< AngleStructures > > regina::PacketData< AngleStructures >::packet ( )

inlineinherited

Returns the packet that holds this data, if there is one.

If this object is being held by a packet p of type PacketOf<Held>, then that packet p will be returned. Otherwise, if this is a "standalone" object of type Held, then this routine will return null.

There is a special case when dealing with a packet q that holds a SnapPea triangulation. Here q is of type PacketOf<SnapPeaTriangulation>, and it holds a Triangulation<3> "indirectly" in the sense that Packetof<SnapPeaTriangulation> derives from SnapPeaTriangulation, which in turn derives from Triangulation<3>. In this scenario:

calling Triangulation<3>::packet() will return null, since there is no "direct" PacketOf<Triangulation<3>>;
calling SnapPeaTriangulation::packet() will return the enclosing packet q, since there is a PacketOf<SnapPeaTriangulation>;
calling the special routine Triangulation<3>::inAnyPacket() will also return the "indirect" enclosing packet q.

The function inAnyPacket() is specific to Triangulation<3>, and is not offered for other Held types.

Returns: the packet that holds this data, or null if this data is not (directly) held by a packet.

◆ packet() [2/2]

std::shared_ptr< const PacketOf< AngleStructures > > regina::PacketData< AngleStructures >::packet ( ) const

inlineinherited

Returns the packet that holds this data, if there is one.

See the non-const version of this function for further details, and in particular for how this functions operations in the special case of a packet that holds a SnapPea triangulation.

Returns: the packet that holds this data, or null if this data is not (directly) held by a packet.

◆ size()

size_t regina::AngleStructures::size ( ) const

inline

Returns the number of angle structures stored in this list.

Returns: the number of angle structures.

◆ spansStrict()

bool regina::AngleStructures::spansStrict ( ) const

inline

Determines whether any convex combination of the angle structures in this list is a strict angle structure.

See AngleStructure::isStrict() for details on strict angle structures.

Returns: true if and only if a strict angle structure can be produced.

◆ spansTaut()

bool regina::AngleStructures::spansTaut ( ) const

inline

Determines whether any angle structure in this list is a taut structure.

Because taut structures always appear as vertices of the angle structure solution space, this routine is equivalent to testing whether any convex combination of the angle structures in this list is a taut structure.

See AngleStructure::isTaut() for details on taut structures.

Returns: true if and only if a taut structure can be produced.

◆ str()

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

◆ structure()

const AngleStructure & regina::AngleStructures::structure ( size_t index ) const

inline

Returns the angle structure at the requested index in this list.

Parameters

index the index of the requested angle structure in this list; this must be between 0 and size()-1 inclusive.

Returns: the angle structure at the requested index.

◆ swap()

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

Swaps the contents of this and the given list.

This routine will behave correctly if other is in fact this list.

Note: This swap function is not marked noexcept, since it fires change events on both lists which may in turn call arbitrary code via any registered packet listeners.

Parameters

other the list whose contents should be swapped with this.

◆ triangulation()

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

inline

Returns the triangulation on which these angle structures lie.

This will be a snapshot frozen in time of the triangulation that was originally passed to the AngleStructures 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.

Warning: As of Regina 7.0, you cannot access this triangulation via the packet tree as Packet::parent(). This is because angle structure lists can now be kept anywhere in the packet tree, or can be kept as standalone objects outside the packet tree entirely.

Returns: a reference to the underlying triangulation.

◆ utf8()

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

◆ writeTextLong()

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

◆ writeTextShort()

void regina::AngleStructures::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.

Member Data Documentation

◆ heldBy_

PacketHeldBy regina::PacketData< AngleStructures >::heldBy_

protectedinherited

Indicates whether this Held object is in fact the inherited data for a PacketOf<Held>.

As a special case, this field is also used to indicate when a Triangulation<3> is in fact the inherited data for a SnapPeaTriangulation. See the PacketHeldBy enumeration for more details on the different values that this data member can take.

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

angle/anglestructures.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ AngleStructures() [1/4]

◆ AngleStructures() [2/4]

◆ AngleStructures() [3/4]

◆ AngleStructures() [4/4]

Member Function Documentation

◆ algorithm()

◆ anonID()

◆ begin()

◆ calculateSpanStrict()

◆ calculateSpanTaut()

◆ detail()

◆ end()

◆ enumerate()

◆ enumerateTautDD()

◆ isTautOnly()

◆ operator!=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ packet() [1/2]

◆ packet() [2/2]

◆ size()

◆ spansStrict()

◆ spansTaut()

◆ str()

◆ structure()

◆ swap()

◆ triangulation()

◆ utf8()

◆ writeTextLong()

◆ writeTextShort()

Member Data Documentation

◆ heldBy_