A collection of normal surfaces in a 3-manifold triangulation. More...

#include <surface/normalsurfaces.h>

Inheritance diagram for regina::NormalSurfaces:

Classes
class	VectorIterator
	A bidirectional iterator that runs through the raw vectors for surfaces in this list. More...

Public Member Functions
	NormalSurfaces (const Triangulation< 3 > &triangulation, NormalCoords coords, NormalList which=NS_LIST_DEFAULT, NormalAlg algHints=NS_ALG_DEFAULT, ProgressTracker *tracker=nullptr)
	A unified "enumeration constructor" for enumerating various classes of normal surfaces within a given triangulation. More...

	NormalSurfaces (const NormalSurfaces &src, NormalTransform transform)
	A unified "transform constructor" for transforming one normal surface list into another. More...

	NormalSurfaces (const NormalSurfaces &src, const SurfaceFilter &filter)
	A "filter constructor" that creates a new list filled with those surfaces from the given list that pass the given filter. More...

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

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

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

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

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

NormalCoords	coords () const
	Returns the coordinate system that was originally used to enumerate the surfaces in this list. More...

NormalList	which () const
	Returns details of which normal surfaces this list represents within the underlying triangulation. More...

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

bool	allowsAlmostNormal () const
	Determines if the coordinate system that was used for enumeration allows for almost normal surfaces. More...

bool	allowsNonCompact () const
	Determines if the coordinate system that was used for enumeration allows for non-compact normal surfaces. More...

bool	allowsSpun () const
	A deprecated alias for allowsNonCompact(). More...

bool	isEmbeddedOnly () const
	Returns whether this list was constructed to contain only properly embedded surfaces. More...

const Triangulation< 3 > &	triangulation () const
	Returns the triangulation in which these normal surfaces live. More...

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

const NormalSurface &	surface (size_t index) const
	Returns the surface at the requested index in this list. More...

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

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

bool	operator== (const NormalSurfaces &other) const
	Determines whether this and the given list contain the same set of normal (or almost normal) surfaces. More...

bool	operator!= (const NormalSurfaces &other) const
	Determines whether this and the given list contain different sets of normal (or almost normal) surfaces. More...

void	writeAllSurfaces (std::ostream &out) const
	Deprecated routine that writes the number of surfaces in this list followed by the details of each surface 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...

std::shared_ptr< PacketOf< NormalSurfaces > >	quadToStandard () const
	Deprecated function that converts the set of all embedded vertex normal surfaces in quadrilateral space to the set of all embedded vertex normal surfaces in standard (tri-quad) space. More...

std::shared_ptr< PacketOf< NormalSurfaces > >	quadOctToStandardAN () const
	Deprecated function that converts the set of all embedded vertex surfaces in quadrilateral-octagon space to the set of all embedded vertex surfaces in standard almost normal (tri-quad-oct) space. More...

std::shared_ptr< PacketOf< NormalSurfaces > >	standardToQuad () const
	Deprecated function that converts the set of all embedded vertex normal surfaces in standard (tri-quad) space to the set of all embedded vertex normal surfaces in quadrilateral space. More...

std::shared_ptr< PacketOf< NormalSurfaces > >	standardANToQuadOct () const
	Deprecated function that converts the set of all embedded vertex surfaces in standard almost normal (tri-quad-oct) space to the set of all embedded vertex surfaces in quadrilateral-octagon space. More...

template<typename Comparison >
void	sort (Comparison &&comp)
	Sorts the surfaces in this list according to the given criterion. More...

std::shared_ptr< PacketOf< NormalSurfaces > >	filter (const SurfaceFilter &filter) const
	Deprecated function that creates a new list filled with those surfaces from this list that pass the given filter. More...

std::shared_ptr< PacketOf< NormalSurfaces > >	filterForLocallyCompatiblePairs () const
	Deprecated function to create a new list filled with those surfaces from this list that have at least one locally compatible partner. More...

std::shared_ptr< PacketOf< NormalSurfaces > >	filterForDisjointPairs () const
	Deprecated function to create a new list filled with those surfaces from this list that have at least one disjoint partner. More...

std::shared_ptr< PacketOf< NormalSurfaces > >	filterForPotentiallyIncompressible () const
	Deprecated function to create a new list filled with those surfaces from this list that "might" represent two-sided incompressible surfaces, according to fast heuristics. More...

MatrixInt	recreateMatchingEquations () const
	Returns the matching equations that were used to create this normal surface list. More...

bool	saveCSVStandard (const char *filename, SurfaceExport additionalFields=regina::surfaceExportAll) const
	Exports this list of normal surfaces as a plain text CSV (comma-separated value) file, using standard coordinates. More...

bool	saveCSVEdgeWeight (const char *filename, SurfaceExport additionalFields=regina::surfaceExportAll) const
	Exports the given list of normal surfaces as a plain text CSV (comma-separated value) file, using edge weight coordinates. More...

VectorIterator	beginVectors () const
	An iterator that gives access to the raw vectors for surfaces in this list, pointing to the beginning of this surface list. More...

VectorIterator	endVectors () const
	An iterator that gives access to the raw vectors for surfaces in this list, pointing past the end of this surface list. More...

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

std::shared_ptr< const PacketOf< NormalSurfaces > >	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< NormalSurfaces > >	enumerate (Triangulation< 3 > &owner, NormalCoords coords, NormalList which=NS_LIST_DEFAULT, NormalAlg algHints=NS_ALG_DEFAULT, ProgressTracker *tracker=nullptr)
	Deprecated routine to enumerate normal surfaces within a given triangulation. More...

Protected Member Functions
	NormalSurfaces (NormalCoords coords, NormalList which, NormalAlg algorithm, const Triangulation< 3 > &triangulation)
	Creates an empty list of normal surfaces with the given parameters. More...

	NormalSurfaces (NormalCoords coords, NormalList which, NormalAlg algorithm, const SnapshotRef< Triangulation< 3 > > &triangulation)
	Creates an empty list of normal surfaces with the given parameters. More...

Protected Attributes
std::vector< NormalSurface >	surfaces_
	Contains all normal surfaces in this list. More...

SnapshotRef< Triangulation< 3 > >	triangulation_
	The triangulation in which these normal surfaces lie. More...

NormalCoords	coords_
	The coordinate system that was originally used to enumerate the normal surfaces in this list. More...

NormalList	which_
	Indicates which normal surfaces these represent within the underlying triangulation. More...

NormalAlg	algorithm_
	Stores the details of the enumeration algorithm that was used to generate this list. More...

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

Friends
class	XMLNormalSurfacesReader

class	XMLLegacyNormalSurfacesReader

class	XMLWriter< NormalSurfaces >

Detailed Description

A collection of normal surfaces in a 3-manifold triangulation.

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

A normal surface 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 normal surface lists (and angle structure lists) can all share the same private copy, so this is not an expensive process.
You should now create normal surface 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 a normal surface 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 NormalSurfaces 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 NormalSurfaces object in the packet tree, you must create a new PacketOf<NormalSurfaces>. This is a packet type, and supports labels, tags, child/parent packets, and event listeners. It derives from NormalSurfaces, and so inherits the full NormalSurfaces 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<NormalSurfaces>, then the appropriate packet change events will be fired. All other events (aside from packetToBeChanged() and packetWasChanged() are managed directly by the PacketOf<NormalSurfaces> wrapper class.

See the NormalSurface class notes for details of what to do when introducing a new coordinate system.

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:

Feature: Allow custom matching equations.

Feature: Allow enumeration with some coordinates explicitly set to zero.

Feature: Allow generating only closed surfaces.

Feature: Generate facets of the solution space representing embedded surfaces.

Constructor & Destructor Documentation

◆ NormalSurfaces() [1/7]

regina::NormalSurfaces::NormalSurfaces	(	const Triangulation< 3 > &	triangulation,
		NormalCoords	coords,
		NormalList	which = `NS_LIST_DEFAULT`,
		NormalAlg	algHints = `NS_ALG_DEFAULT`,
		ProgressTracker *	tracker = `nullptr`
	)

inline

A unified "enumeration constructor" for enumerating various classes of normal surfaces within a given triangulation.

The NormalCoords argument allows you to specify an underlying coordinate system in which to do the enumeration (e.g., standard coordinates, quadrilateral coordinates or almost normal coordinates). This choice of coordinate system will affect which surfaces are produced, since vertex/fundamental surfaces in one system are not necessarily vertex/fundamental in another.

The NormalList argument is a combination of flags that allows you to specify exactly which normal surfaces you require. This includes (i) whether you want all vertex surfaces or all fundamental surfaces, which defaults to NS_VERTEX if you specify neither or both; and (ii) whether you want only properly embedded surfaces or you also wish to include immersed and/or singular surfaces, which defaults to NS_EMBEDDED_ONLY if you specify neither or both.

The NormalAlg 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 NS_ALG_DEFAULT (which makes no hints at all) will allow Regina to choose what it thinks will be the most efficient method.

The enumerated surfaces will be stored in this new normal surface list, and their representations will be scaled down to use the smallest possible integer coordinates.

Unlike the old enumerate() function, the new normal surface 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 surfaces 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.

If an error occurs, then this routine will thrown an exception. In this case, no normal surface list will be created, and the progress tracker (if passed) will be marked as finished. See the exception specifications below for details.

Exceptions

InvalidArgument	the matching equations could not be created for the given triangulation in the given coordinate system, due to an error that should have been preventable with the right checks in advance. This can only happen in certain coordinate systems, and for all such coordinate systems this is explicitly described in the HyperCoords enum documentation.
UnsolvedCase	the matching equations could not be created for the given triangulation in the given coordinate system, due to an error that was "genuinely" unforseeable. Again this can only happen in certain coordinate systems, where this is explicitly described in the HyperCoords enum documentation.

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 upon which this list of normal surfaces will be based.
coords	the coordinate system to be used. This must be one of the system that Regina is able to use for enumeration; this is documented alongside each NormalCoords enum value.
which	indicates which normal surfaces should be enumerated.
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.

◆ NormalSurfaces() [2/7]

regina::NormalSurfaces::NormalSurfaces	(	const NormalSurfaces &	src,
		NormalTransform	transform
	)

A unified "transform constructor" for transforming one normal surface list into another.

The available transformations include:

conversions between vertex surfaces in different coordinate systems, including those formerly provided by the deprecated functions quadToStandard(), quadOctToStandardAN(), standardToQuad() and standardANToQuadOct();
filters that select a subset of surfaces, including those formerly provided by the deprecated functions filterForLocallyCompatiblePairs(), filterForDisjointPairs(), and filterForPotentiallyIncompressible().

Each transformation comes with its own set of preconditions, as documented alongside the various NormalTransform enumeration constants. These preconditions will be checked, and if any of them fails then this constructor will throw an exception (see below).

Unlike the old conversion and filter functions, this constructor will not insert the new normal surface list into the packet tree.

Exceptions

FailedPrecondition the preconditions for the given transformation were not met. See each NormalTransform enum constant for the corresponding set of preconditions.

Parameters

src	the normal surface list that we wish to transform; this will not be modified.
transform	the specific transformation to apply.

◆ NormalSurfaces() [3/7]

regina::NormalSurfaces::NormalSurfaces	(	const NormalSurfaces &	src,
		const SurfaceFilter &	filter
	)

A "filter constructor" that creates a new list filled with those surfaces from the given list that pass the given filter.

Unlike the old filter() function, this constructor will not insert the new normal surface list into the packet tree.

For this new filtered list, which() will include the NS_CUSTOM flag, and algorithm() will include the NS_ALG_CUSTOM flag.

Parameters

src	the normal surface list that we wish to filter; this will not be modified.
filter	the filter to apply to the given list.

◆ NormalSurfaces() [4/7]

regina::NormalSurfaces::NormalSurfaces ( const NormalSurfaces & )

default

Constructs a new copy of the given list.

◆ NormalSurfaces() [5/7]

regina::NormalSurfaces::NormalSurfaces ( NormalSurfaces && 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.

◆ NormalSurfaces() [6/7]

regina::NormalSurfaces::NormalSurfaces	(	NormalCoords	coords,
		NormalList	which,
		NormalAlg	algorithm,
		const Triangulation< 3 > &	triangulation
	)

inlineprotected

Creates an empty list of normal surfaces with the given parameters.

◆ NormalSurfaces() [7/7]

regina::NormalSurfaces::NormalSurfaces	(	NormalCoords	coords,
		NormalList	which,
		NormalAlg	algorithm,
		const SnapshotRef< Triangulation< 3 > > &	triangulation
	)

inlineprotected

Creates an empty list of normal surfaces with the given parameters.

Member Function Documentation

◆ algorithm()

NormalAlg regina::NormalSurfaces::algorithm ( ) const

inline

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

These may not be the same NormalAlg 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.

◆ allowsAlmostNormal()

bool regina::NormalSurfaces::allowsAlmostNormal ( ) const

inline

Determines if the coordinate system that was used for enumeration allows for almost normal surfaces.

This does not test whether any of the surfaces in this list actually contain octagons: it simply returns a basic property of the coordinate system that was used for enumeration.

Returns: true if and only if almost normal surfaces are supported.

◆ allowsNonCompact()

bool regina::NormalSurfaces::allowsNonCompact ( ) const

inline

Determines if the coordinate system that was used for enumeration allows for non-compact normal surfaces.

This does not test whether any of the surfaces in this list are actually non-compact: it simply returns a basic property of the coordinate system that was used for enumeration.

Returns: true if and only if non-compact normal surfaces are supported.

◆ allowsSpun()

bool regina::NormalSurfaces::allowsSpun ( ) const

inline

A deprecated alias for allowsNonCompact().

Deprecated:: This routine has been renamed to allowsNonCompact(), for consistency between three and four dimensions. See allowsNonCompact() for further details.

Returns: c true if and only if non-compact normal surfaces are supported.

◆ anonID()

std::string regina::PacketData< NormalSurfaces >::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::NormalSurfaces::begin ( ) const

inline

Returns an iterator at the beginning of this list of surfaces.

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

NormalSurfaces list(...);

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

regina::NormalSurfaces::NormalSurfaces

NormalSurfaces(const Triangulation< 3 > &triangulation, NormalCoords coords, NormalList which=NS_LIST_DEFAULT, NormalAlg algHints=NS_ALG_DEFAULT, ProgressTracker *tracker=nullptr)

A unified "enumeration constructor" for enumerating various classes of normal surfaces within a given...

Definition: normalsurfaces.h:1685

In Python, a normal surface list can be treated as an iterable object:

list = NormalSurfaces(...)
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.

◆ beginVectors()

NormalSurfaces::VectorIterator regina::NormalSurfaces::beginVectors ( ) const

inline

An iterator that gives access to the raw vectors for surfaces in this list, pointing to the beginning of this surface list.

In Python, beginVectors() and endVectors() are replaced by a single routine vectors(), which returns an iterable object:

list = NormalSurfaces(...)
for v in list.vectors():
    ...

Python: Not present; use vectors() instead.

Returns: an iterator at the beginning of this surface list.

◆ coords()

NormalCoords regina::NormalSurfaces::coords ( ) const

inline

Returns the coordinate system that was originally used to enumerate the surfaces in this list.

Returns: the coordinate system used.

◆ detail()

std::string regina::Output< NormalSurfaces , 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::NormalSurfaces::end ( ) const

inline

Returns an iterator beyond the end of this list of surfaces.

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

See the begin() documentation for further details.

Returns: an iterator beyond the end of this list.

◆ endVectors()

NormalSurfaces::VectorIterator regina::NormalSurfaces::endVectors ( ) const

inline

An iterator that gives access to the raw vectors for surfaces in this list, pointing past the end of this surface list.

This iterator is not dereferenceable.

In Python, beginVectors() and endVectors() are replaced by a single routine vectors(), which returns an iterable object; see the beginVectors() documentation for further details.

Python: Not present; use vectors() instead.

Returns: an iterator past the end of this surface list.

◆ enumerate()

static std::shared_ptr< PacketOf< NormalSurfaces > > regina::NormalSurfaces::enumerate	(	Triangulation< 3 > &	owner,
		NormalCoords	coords,
		NormalList	which = `NS_LIST_DEFAULT`,
		NormalAlg	algHints = `NS_ALG_DEFAULT`,
		ProgressTracker *	tracker = `nullptr`
	)

static

Deprecated routine to enumerate normal surfaces within a given triangulation.

This static routine is identical to calling the class "enumeration constructor" with the given arguments, but with three 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 normal surface list in a packet and inserts it beneath owner in the packet tree (unlike the class constructor, which creates a plain NormalSurfaces 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.
If there is an error, this routine will return null (unlike the class constructor, which throws an exception).

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 normal surface list, but the resulting packet will be orphaned.

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

Deprecated:: Just call the NormalSurfaces "enumeration 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 upon which this list of normal surfaces will be based.
coords	the coordinate system to be used.
which	indicates which normal surfaces should be enumerated.
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.

Returns: the new normal surface list, or null if an error occurred.

◆ filter()

std::shared_ptr< PacketOf< NormalSurfaces > > regina::NormalSurfaces::filter ( const SurfaceFilter & filter ) const

Deprecated function that creates a new list filled with those surfaces from this list that pass the given filter.

This routine is identical to calling the "filter constructor" NormalSurfaces(*this, filter), except that it also wraps the output list in a packet and insert it beneath the same parent packet as this input list. (If this list has no parent, then then new list will be orphaned.)

See the "filter constructor" for details on how this routine works.

Deprecated:: Just call the NormalSurfaces "filter constructor".

Returns: the new filtered list of surfaces.

◆ filterForDisjointPairs()

std::shared_ptr< PacketOf< NormalSurfaces > > regina::NormalSurfaces::filterForDisjointPairs ( ) const

Deprecated function to create a new list filled with those surfaces from this list that have at least one disjoint partner.

This routine is identical to calling the "transform constructor" NormalSurfaces(*this, NS_FILTER_COMPATIBLE), but with two key differences:

Unlike the transform constructor, this routine will also wrap the new normal surface list in a packet and insert it beneath the same parent packet as this input list. (If this list has no parent, then then new list will be orphaned.)
If a precondition is not satisfied, then the class constructor will throw an exception, whereas this routine will simply return null.

See the class "transform constructor" for details on how this routine works. See the NormalList enumeration (in particular, the NS_FILTER_COMPATIBLE value) for more details on disjointness testing, some important caveats, and for preconditions on the input list.

Deprecated:: Just call the NormalSurfaces "transform constructor".

Todo:: Deal properly with surfaces that are too large to handle.

Returns: the new filtered list of surfaces.

◆ filterForLocallyCompatiblePairs()

std::shared_ptr< PacketOf< NormalSurfaces > > regina::NormalSurfaces::filterForLocallyCompatiblePairs ( ) const

Deprecated function to create a new list filled with those surfaces from this list that have at least one locally compatible partner.

This routine is identical to calling the "transform constructor" NormalSurfaces(*this, NS_FILTER_COMPATIBLE), but with two key differences:

Unlike the transform constructor, this routine will also wrap the new normal surface list in a packet and insert it beneath the same parent packet as this input list. (If this list has no parent, then then new list will be orphaned.)
If a precondition is not satisfied, then the class constructor will throw an exception, whereas this routine will simply return null.

See the class "transform constructor" for details on how this routine works. See the NormalList enumeration (in particular, the NS_FILTER_COMPATIBLE value) for more details on local compatibility and for preconditions on the input list.

Deprecated:: Just call the NormalSurfaces "transform constructor".

Returns: the new filtered list of surfaces.

◆ filterForPotentiallyIncompressible()

std::shared_ptr< PacketOf< NormalSurfaces > > regina::NormalSurfaces::filterForPotentiallyIncompressible ( ) const

Deprecated function to create a new list filled with those surfaces from this list that "might" represent two-sided incompressible surfaces, according to fast heuristics.

This routine is identical to calling the "transform constructor" NormalSurfaces(*this, NS_FILTER_INCOMPRESSIBLE), but with two key differences:

Unlike the transform constructor, this routine will also wrap the new normal surface list in a packet and insert it beneath the same parent packet as this input list. (If this list has no parent, then then new list will be orphaned.)
If a precondition is not satisfied, then the class constructor will throw an exception, whereas this routine will simply return null.

See the class "transform constructor" for details on how this routine works. See the NormalList enumeration (in particular, the NS_FILTER_INCOMPRESSIBLE value) for more details on what "potential incompressibility" testing means, the heuristics behind it, and for preconditions on the triangulation and the input list.

Deprecated:: Just call the NormalSurfaces "transform constructor".

Returns: the new filtered list of surfaces.

◆ isEmbeddedOnly()

bool regina::NormalSurfaces::isEmbeddedOnly ( ) const

inline

Returns whether this list was constructed to contain only properly embedded surfaces.

If this returns false, it does not guarantee that immersed and/or singular surfaces are present; it merely indicates that they were not deliberately excluded (for instance, the quadrilateral constraints were not enforced).

Returns: true if this list was constructed to contain only properly embedded surfaces, or false otherwise.

◆ operator!=()

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

inline

Determines whether this and the given list contain different sets of normal (or almost normal) surfaces.

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

Like the comparison operators for NormalSurface, it does not matter whether the lists work with different triangulations, or different encodings, or if one but not the other supports almost normal and/or spun-normal surfaces. The individual surfaces will simply be compared by examining or computing the number of discs of each type.

In particular, this routine is safe to call even if this and the given list work with different triangulations:

If the two triangulations have the same size, then this routine will compare surfaces as though they were transplanted into the same triangulation using the same tetrahedron numbering and the same disc types.
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 normal or almost normal surfaces, or false if they do.

◆ operator=() [1/2]

NormalSurfaces & regina::NormalSurfaces::operator= ( const NormalSurfaces & 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=() [2/2]

NormalSurfaces & regina::NormalSurfaces::operator= ( NormalSurfaces && 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==()

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

Determines whether this and the given list contain the same set of normal (or almost normal) surfaces.

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

Like the comparison operators for NormalSurface, it does not matter whether the lists work with different triangulations, or different encodings, or if one but not the other supports almost normal and/or spun-normal surfaces. The individual surfaces will simply be compared by examining or computing the number of discs of each type.

In particular, this routine is safe to call even if this and the given list work with different triangulations:

If the two triangulations have the same size, then this routine will compare surfaces as though they were transplanted into the same triangulation using the same tetrahedron numbering and the same disc types.
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 normal or almost normal surfaces, or false if not.

◆ packet() [1/2]

std::shared_ptr< PacketOf< NormalSurfaces > > regina::PacketData< NormalSurfaces >::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< NormalSurfaces > > regina::PacketData< NormalSurfaces >::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.

◆ quadOctToStandardAN()

std::shared_ptr< PacketOf< NormalSurfaces > > regina::NormalSurfaces::quadOctToStandardAN ( ) const

Deprecated function that converts the set of all embedded vertex surfaces in quadrilateral-octagon space to the set of all embedded vertex surfaces in standard almost normal (tri-quad-oct) space.

The input list will be taken as this list; the output list will be returned and also inserted into the packet tree (see below).

This routine is identical to calling the "transform constructor" NormalSurfaces(*this, NS_CONV_REDUCED_TO_STD), but with two key differences:

Unlike the transform constructor, this routine will also wrap the new normal surface list in a packet and insert it beneath the same parent packet as this input list. (If this list has no parent, then then new list will be orphaned.)
If a precondition is not satisfied, then the class constructor will throw an exception, whereas this routine will simply return null.

See the class "transform constructor" for details on how this routine works and what the arguments mean. See the NormalList enumeration (in particular, the NS_CONV_REDUCED_TO_STD value) for details on the algorithm, and for preconditions on the triangulation and the input list.

Deprecated:: Just call the NormalSurfaces "transform constructor".

Returns: a full list of vertex surfaces in standard almost normal coordinates, or null if any of the preconditions were not satisfied.

◆ quadToStandard()

std::shared_ptr< PacketOf< NormalSurfaces > > regina::NormalSurfaces::quadToStandard ( ) const

Deprecated function that converts the set of all embedded vertex normal surfaces in quadrilateral space to the set of all embedded vertex normal surfaces in standard (tri-quad) space.

The input list will be taken as this list; the output list will be returned and also inserted into the packet tree (see below).

This routine is identical to calling the "transform constructor" NormalSurfaces(*this, NS_CONV_REDUCED_TO_STD), but with two key differences:

Unlike the transform constructor, this routine will also wrap the new normal surface list in a packet and insert it beneath the same parent packet as this input list. (If this list has no parent, then then new list will be orphaned.)
If a precondition is not satisfied, then the class constructor will throw an exception, whereas this routine will simply return null.

See the class "transform constructor" for details on how this routine works and what the arguments mean. See the NormalList enumeration (in particular, the NS_CONV_REDUCED_TO_STD value) for details on the algorithm, and for preconditions on the triangulation and the input list.

Deprecated:: Just call the NormalSurfaces "transform constructor".

Returns: a full list of vertex normal surfaces in standard normal coordinates, or null if any of the preconditions were not satisfied.

◆ recreateMatchingEquations()

MatrixInt regina::NormalSurfaces::recreateMatchingEquations ( ) const

Returns the matching equations that were used to create this normal surface list.

The matrix is not cached: multiple calls to this routine will result in the construction of multiple matrices. This routine in fact merely calls makeMatchingEquations() with the appropriate parameters.

The format of the matrix is identical to that returned by makeMatchingEquations().

Note that there are situations in which makeMatchingEquations() throws an exception (because the triangulation is not supported by the chosen coordinate system). However, this routine will always succeed, because if makeMatchingEquations() had failed then this normal surface list would not have been created in the first place.

Returns: the matching equations used to create this normal surface list.

◆ saveCSVEdgeWeight()

bool regina::NormalSurfaces::saveCSVEdgeWeight	(	const char *	filename,
		SurfaceExport	additionalFields = `regina::surfaceExportAll`
	)		const

Exports the given list of normal surfaces as a plain text CSV (comma-separated value) file, using edge weight coordinates.

CSV files are human-readable and human-editable, and are suitable for importing into spreadsheets and databases.

The surfaces will be exported in edge weight coordinates. Thus there will be one coordinate for each edge of the underlying triangulation; each such coordinate will become a separate field in the CSV file.

As well as the normal surface coordinates, additional properties of the normal surfaces (such as Euler characteristic, orientability, and so on) can be included as extra fields in the export. Users can select precisely which properties to include by passing a bitwise OR combination of constants from the regina::SurfaceExportFields enumeration type.

The CSV format used here begins with a header row, and uses commas as field separators. Text fields with arbitrary contents are placed inside double quotes, and the double quote character itself is represented by a pair of double quotes. Thus the string my "normal" surface's name would be stored as "my ""normal"" surface's name".

Internationalisation: This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines. Any user strings such as surface names will be written in UTF-8.

Parameters

filename	the name of the CSV file to export to.
additionalFields	a bitwise OR combination of constants from regina::SurfaceExportFields indicating which additional properties of surfaces should be included in the export.

Returns: true if the export was successful, or false otherwise.

◆ saveCSVStandard()

bool regina::NormalSurfaces::saveCSVStandard	(	const char *	filename,
		SurfaceExport	additionalFields = `regina::surfaceExportAll`
	)		const

Exports this list of normal surfaces as a plain text CSV (comma-separated value) file, using standard coordinates.

CSV files are human-readable and human-editable, and are suitable for importing into spreadsheets and databases.

The surfaces will be exported in standard coordinates (tri-quad coordinates for normal surfaces, or tri-quad-oct coordinates for almost normal surfaces). Each coordinate will become a separate field in the CSV file.

As well as the normal surface coordinates, additional properties of the normal surfaces (such as Euler characteristic, orientability, and so on) can be included as extra fields in the export. Users can select precisely which properties to include by passing a bitwise OR combination of constants from the regina::SurfaceExportFields enumeration type.

The CSV format used here begins with a header row, and uses commas as field separators. Text fields with arbitrary contents are placed inside double quotes, and the double quote character itself is represented by a pair of double quotes. Thus the string my "normal" surface's name would be stored as "my ""normal"" surface's name".

Internationalisation: This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines. Any user strings such as surface names will be written in UTF-8.

Parameters

filename	the name of the CSV file to export to.
additionalFields	a bitwise OR combination of constants from regina::SurfaceExportFields indicating which additional properties of surfaces should be included in the export.

Returns: true if the export was successful, or false otherwise.

◆ size()

size_t regina::NormalSurfaces::size ( ) const

inline

Returns the number of surfaces stored in this list.

Returns: the number of surfaces.

◆ sort()

template<typename Comparison >

void regina::NormalSurfaces::sort ( Comparison && comp )

inline

Sorts the surfaces in this list according to the given criterion.

This sort is stable, i.e., surfaces that are equivalent under the given criterion will remain in the same relative order.

The implementation of this routine uses std::stable_sort.

Python: This is available in Python, and comp may be a pure Python function.

Parameters

comp	a binary function (or other callable object) that accepts two const NormalSurface references, and returns `true` if and only if the first surface should appear before the second in the sorted list.

◆ standardANToQuadOct()

std::shared_ptr< PacketOf< NormalSurfaces > > regina::NormalSurfaces::standardANToQuadOct ( ) const

Deprecated function that converts the set of all embedded vertex surfaces in standard almost normal (tri-quad-oct) space to the set of all embedded vertex surfaces in quadrilateral-octagon space.

The input list will be taken as this list; the output list will be returned and also inserted into the packet tree (see below).

This routine is identical to calling the "transform constructor" NormalSurfaces(*this, NS_CONV_STD_TO_REDUCED), but with two key differences:

Unlike the transform constructor, this routine will also wrap the new normal surface list in a packet and insert it beneath the same parent packet as this input list. (If this list has no parent, then then new list will be orphaned.)
If a precondition is not satisfied, then the class constructor will throw an exception, whereas this routine will simply return null.

See the class "transform constructor" for details on how this routine works and what the arguments mean. See the NormalList enumeration (in particular, the NS_CONV_STD_TO_REDUCED value) for details on the algorithm, and for preconditions on the triangulation and the input list.

Deprecated:: Just call the NormalSurfaces "transform constructor".

Returns: a full list of vertex surfaces in quadrilateral-octagon coordinates, or null if any of the preconditions were not satisfied.

◆ standardToQuad()

std::shared_ptr< PacketOf< NormalSurfaces > > regina::NormalSurfaces::standardToQuad ( ) const

Deprecated function that converts the set of all embedded vertex normal surfaces in standard (tri-quad) space to the set of all embedded vertex normal surfaces in quadrilateral space.

The input list will be taken as this list; the output list will be returned and also inserted into the packet tree (see below).

This routine is identical to calling the "transform constructor" NormalSurfaces(*this, NS_CONV_STD_TO_REDUCED), but with two key differences:

Unlike the transform constructor, this routine will also wrap the new normal surface list in a packet and insert it beneath the same parent packet as this input list. (If this list has no parent, then then new list will be orphaned.)
If a precondition is not satisfied, then the class constructor will throw an exception, whereas this routine will simply return null.

See the class "transform constructor" for details on how this routine works and what the arguments mean. See the NormalList enumeration (in particular, the NS_CONV_STD_TO_REDUCED value) for details on the algorithm, and for preconditions on the triangulation and the input list.

Deprecated:: Just call the NormalSurfaces "transform constructor".

Returns: a full list of vertex normal surfaces in quadrilateral coordinates, or null if any of the preconditions were not satisfied.

◆ str()

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

◆ surface()

const NormalSurface & regina::NormalSurfaces::surface ( size_t index ) const

inline

Returns the surface at the requested index in this list.

Parameters

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

Returns: the normal surface at the requested index in this list.

◆ swap()

void regina::NormalSurfaces::swap ( NormalSurfaces & 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::NormalSurfaces::triangulation ( ) const

inline

Returns the triangulation in which these normal surfaces live.

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

◆ which()

NormalList regina::NormalSurfaces::which ( ) const

inline

Returns details of which normal surfaces this list represents within the underlying triangulation.

This may not be the same NormalList that was passed to the class constructor. In particular, default values will have been explicitly filled in (such as NS_VERTEX and/or NS_EMBEDDED_ONLY), and invalid and/or redundant values will have been removed.

Returns: details of what this list represents.

◆ writeAllSurfaces()

void regina::NormalSurfaces::writeAllSurfaces ( std::ostream & out ) const

Deprecated routine that writes the number of surfaces in this list followed by the details of each surface to the given output stream.

Output will be over many lines.

Deprecated:: All of the information that this routine outputs is also 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 to which to write.

◆ writeTextLong()

void regina::NormalSurfaces::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::NormalSurfaces::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

◆ algorithm_

NormalAlg regina::NormalSurfaces::algorithm_

protected

Stores the details of the enumeration algorithm that was used to generate this list.

This might not be the same as the algHints flag that was originally passed to the enumeration routine (e.g., if invalid or inappropriate flags were passed).

◆ coords_

NormalCoords regina::NormalSurfaces::coords_

protected

The coordinate system that was originally used to enumerate the normal surfaces in this list.

◆ heldBy_

PacketHeldBy regina::PacketData< NormalSurfaces >::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.

◆ surfaces_

std::vector<NormalSurface> regina::NormalSurfaces::surfaces_

protected

Contains all normal surfaces in this list.

◆ triangulation_

SnapshotRef<Triangulation<3> > regina::NormalSurfaces::triangulation_

protected

The triangulation in which these normal surfaces lie.

◆ which_

NormalList regina::NormalSurfaces::which_

protected

Indicates which normal surfaces these represent within the underlying triangulation.

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

surface/normalsurfaces.h

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ NormalSurfaces() [1/7]

◆ NormalSurfaces() [2/7]

◆ NormalSurfaces() [3/7]

◆ NormalSurfaces() [4/7]

◆ NormalSurfaces() [5/7]

◆ NormalSurfaces() [6/7]

◆ NormalSurfaces() [7/7]

Member Function Documentation

◆ algorithm()

◆ allowsAlmostNormal()

◆ allowsNonCompact()

◆ allowsSpun()

◆ anonID()

◆ begin()

◆ beginVectors()

◆ coords()

◆ detail()

◆ end()

◆ endVectors()

◆ enumerate()

◆ filter()

◆ filterForDisjointPairs()

◆ filterForLocallyCompatiblePairs()

◆ filterForPotentiallyIncompressible()

◆ isEmbeddedOnly()

◆ operator!=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ packet() [1/2]

◆ packet() [2/2]

◆ quadOctToStandardAN()

◆ quadToStandard()

◆ recreateMatchingEquations()

◆ saveCSVEdgeWeight()

◆ saveCSVStandard()

◆ size()

◆ sort()

◆ standardANToQuadOct()

◆ standardToQuad()

◆ str()

◆ surface()

◆ swap()

◆ triangulation()

◆ utf8()

◆ which()

◆ writeAllSurfaces()

◆ writeTextLong()

◆ writeTextShort()

Member Data Documentation

◆ algorithm_

◆ coords_

◆ heldBy_

◆ surfaces_

◆ triangulation_

◆ which_