Normal Surfaces

Normal surfaces in 3-manifold triangulations. More...

## Classes

struct | regina::NDiscSpec
| Specifies a single normal disc in a normal surface. More...
class | regina::NDiscSetTet
| Represents a set of normal discs inside a single tetrahedron. More...
class | regina::NDiscSetTetData< T >
| Stores data of type `T` for every normal disc inside a single tetrahedron. More...
class | regina::NDiscSetSurface
| Represents the set of all normal discs forming a normal surface. More...
class | regina::NDiscSetSurfaceData< T >
| Stores data of type `T` for every normal disc within a particular normal surface. More...
class | regina::NDiscSpecIterator
| An iterator used for running through all normal discs in a normal surface. More...
struct | regina::NDiscType
| Identifies a single normal or almost normal disc type within a triangulation. More...
struct | regina::NormalInfo< coordType >
| A template that stores information about a particular normal coordinate system. More...
class | regina::NNormalSurfaceVector
| Stores the vector of a single normal surface in a 3-manifold. More...
class | regina::NNormalSurface
| Represents a single normal surface in a 3-manifold. More...
struct | regina::PacketInfo< PACKET_NORMALSURFACELIST >
| Stores information about the normal surface list packet. More...
class | regina::NNormalSurfaceList
| A packet representing a collection of normal surfaces in a 3-manifold. More...
struct | regina::NPrismSpec
| Specifies a single triangular prism in a tetrahedron. More...
class | regina::NPrismSetSurface
| Represents the set of prisms defined by slicing along all the quads in a particular normal surface. More...
struct | regina::NormalInfo< NS_AN_STANDARD >
| Stores information about standard almost normal coordinates. More...
class | regina::NNormalSurfaceVectorANStandard
| An almost normal surface vector using standard triangle-quad-oct coordinates. More...
class | regina::NNormalSurfaceVectorMirrored
| A normal surface vector that is mirrored in another coordinate system to avoid frequent lengthy calculations. More...
struct | regina::NormalInfo< NS_ORIENTED >
| Stores information about transversely oriented standard normal coordinates. More...
class | regina::NNormalSurfaceVectorOriented
| A normal surface vector using transversely oriented standard (triangle-quad) coordinates. More...
struct | regina::NormalInfo< NS_ORIENTED_QUAD >
| Stores information about transversely oriented quad normal coordinates. More...
class | regina::NNormalSurfaceVectorOrientedQuad
| A normal surface vector using transversely oriented quadrilateral coordinates. More...
struct | regina::NormalInfo< NS_QUAD >
| Stores information about quad normal coordinates. More...
class | regina::NNormalSurfaceVectorQuad
| A normal surface vector using quad coordinates. More...
struct | regina::NormalInfo< NS_AN_QUAD_OCT >
| Stores information about quad-oct almost normal coordinates. More...
class | regina::NNormalSurfaceVectorQuadOct
| An almost normal surface vector using quad-oct coordinates. More...
struct | regina::NormalInfo< NS_STANDARD >
| Stores information about standard normal coordinates. More...
class | regina::NNormalSurfaceVectorStandard
| A normal surface vector using standard triangle-quad coordinates. More...
struct | regina::SurfaceFilterInfo< filterType >
| A template that stores information about a particular type of normal surface filter. More...
struct | regina::PacketInfo< PACKET_SURFACEFILTER >
| Stores information about the normal surface filter packet type. More...
struct | regina::SurfaceFilterInfo< NS_FILTER_DEFAULT >
| Stores information about the default accept-all surface filter. More...
class | regina::NSurfaceFilter
| A packet that accepts or rejects normal surfaces. More...
class | regina::NSurfaceSubset
| Represents a subset of a normal surface list. More...
class | regina::NXMLFilterReader
| An XML element reader that reads the specific details of a normal surface filter. More...
class | regina::NXMLFilterPacketReader
| An XML packet reader that reads a single surface filter. More...
class | regina::NXMLNormalSurfaceReader
| An XML element reader that reads a single normal surface. More...
class | regina::NXMLNormalSurfaceListReader
| An XML packet reader that reads a single normal surface list. More...
struct | regina::SurfaceFilterInfo< NS_FILTER_COMBINATION >
| Stores information about the combination surface filter. More...
class | regina::NSurfaceFilterCombination
| A normal surface filter that simply combines other filters. More...
struct | regina::SurfaceFilterInfo< NS_FILTER_PROPERTIES >
| Stores information about the property-based surface filter. More...
class | regina::NSurfaceFilterProperties
| A normal surface filter that filters by basic properties of the normal surface. More...

## Macros

#define | REGINA_NORMAL_SURFACE_FLAVOUR(class_, id)
| Defines various constants, types and virtual functions for a subclass of NNormalSurfaceVector. More...
#define | REGINA_SURFACE_FILTER(class_, id)
| Defines various constants, types and virtual functions for a descendant class of NSurfaceFilter. More...

## Typedefs

typedef NewFunction1 < NNormalSurfaceVector, size_t > | regina::NewNormalSurfaceVector
| A legacy typedef provided for backward compatibility only. More...
typedef regina::Flags < NormalListFlags > | regina::NormalList
| A combination of flags for types of normal surface lists. More...
typedef regina::Flags < NormalAlgFlags > | regina::NormalAlg
| A combination of flags for types of normal surface lists. More...

## Enumerations

enum | regina::NormalCoords { regina::NS_STANDARD = 0, regina::NS_QUAD = 1, regina::NS_AN_LEGACY = 100, regina::NS_AN_QUAD_OCT = 101, regina::NS_AN_STANDARD = 102, regina::NS_EDGE_WEIGHT = 200, regina::NS_TRIANGLE_ARCS = 201, regina::NS_FACE_ARCS = 201, regina::NS_ORIENTED = 300, regina::NS_ORIENTED_QUAD = 301 }
| Represents different coordinate systems that can be used for enumerating and displaying normal surfaces. More...
enum | regina::NormalListFlags { regina::NS_LIST_DEFAULT = 0x0000, regina::NS_EMBEDDED_ONLY = 0x0001, regina::NS_IMMERSED_SINGULAR = 0x0002, regina::NS_VERTEX = 0x0004, regina::NS_FUNDAMENTAL = 0x0008, regina::NS_LEGACY = 0x4000, regina::NS_CUSTOM = 0x8000 }
| Represents different lists of normal surfaces that might be constructed for a given triangulation. More...

enum

regina::NormalAlgFlags {
regina::NS_ALG_DEFAULT = 0x0000, regina::NS_VERTEX_VIA_REDUCED = 0x0001, regina::NS_VERTEX_STD_DIRECT = 0x0002, regina::NS_VERTEX_TREE = 0x0010,
regina::NS_VERTEX_DD = 0x0020, regina::NS_HILBERT_PRIMAL = 0x0100, regina::NS_HILBERT_DUAL = 0x0200, regina::NS_HILBERT_CD = 0x0400,
regina::NS_HILBERT_FULLCONE = 0x0800, regina::NS_ALG_LEGACY = 0x4000, regina::NS_ALG_CUSTOM = 0x8000
}

| Represents options and variants of algorithms for enumerating various types of normal surfaces. More...
enum | regina::SurfaceFilterType { regina::NS_FILTER_DEFAULT = 0, regina::NS_FILTER_PROPERTIES = 1, regina::NS_FILTER_COMBINATION = 2 }
| Represents different types of filter classes that can be used to filter lists of normal surfaces in 3-manifold triangulations. More...

## Functions

template<typename FunctionObject >
FunctionObject::ReturnType | regina::forCoords (NormalCoords coords, FunctionObject func, typename FunctionObject::ReturnType defaultReturn)
| Allows the user to call a template function whose template parameter matches a given value of NormalCoords, which is not known until runtime. More...
template<typename VoidFunctionObject >
void | regina::forCoords (NormalCoords coords, VoidFunctionObject func)
| Allows the user to call a template function whose template parameter matches a given value of NormalCoords, which is not known until runtime. More...
template<typename FunctionObject >
FunctionObject::ReturnType | regina::forFlavour (NormalCoords coords, FunctionObject func, typename FunctionObject::ReturnType defaultReturn)
| A deprecated alias for the registry-based template function forCoords(). More...
template<typename VoidFunctionObject >
void | regina::forFlavour (NormalCoords coords, VoidFunctionObject func)
| A deprecated alias for the registry-based template function forCoords(). More...
template<typename FunctionObject >
FunctionObject::ReturnType | regina::forFilter (SurfaceFilterType filter, FunctionObject func, typename FunctionObject::ReturnType defaultReturn)
| Allows the user to call a template function whose template parameter matches a given value of SurfaceFilterType, which is not known until runtime. More...
template<typename VoidFunctionObject >
void | regina::forFilter (SurfaceFilterType filter, VoidFunctionObject func)
| Allows the user to call a template function whose template parameter matches a given value of SurfaceFilterType, which is not known until runtime. More...
REGINA_API std::ostream & | regina::operator<< (std::ostream &out, const NDiscSpec &spec)
| Writes the given disc specifier to the given output stream. More...
REGINA_API bool | regina::numberDiscsAwayFromVertex (int discType, int vertex)
| Determines whether or not normal discs of the given type are numbered away from the given vertex. More...
REGINA_API bool | regina::discOrientationFollowsEdge (int discType, int vertex, int edgeStart, int edgeEnd)
| Determines whether or not the natural boundary orientation of a normal disc of the given type follows the given directed normal arc. More...
REGINA_API std::ostream & | regina::operator<< (std::ostream &out, const NDiscType &type)
| Writes the given disc type to the given output stream. More...
REGINA_API NNormalSurfaceVector * | regina::makeZeroVector (const NTriangulation *triangulation, NormalCoords coords)
| Returns a new normal surface vector of the appropriate length for the given triangulation and the given coordinate system. More...
REGINA_API NMatrixInt * | regina::makeMatchingEquations (NTriangulation *triangulation, NormalCoords coords)
| Creates a new set of normal surface matching equations for the given triangulation using the given coordinate system. More...
REGINA_API NEnumConstraintList * | regina::makeEmbeddedConstraints (NTriangulation *triangulation, NormalCoords coords)
| Creates a new set of validity constraints representing the condition that normal surfaces be embedded. More...
NormalList | regina::operator| (NormalListFlags lhs, NormalListFlags rhs)
| Returns the bitwise OR of the two given flags. More...
NormalAlg | regina::operator| (NormalAlgFlags lhs, NormalAlgFlags rhs)
| Returns the bitwise OR of the two given flags. More...
REGINA_API std::ostream & | regina::operator<< (std::ostream &out, const NPrismSpec &spec)
| Writes the given prism specifier to the given output stream. More...

## Variables

REGINA_API const int | regina::vertexSplit [4][4]
| Lists which vertex splits separate which pairs of vertices. More...
REGINA_API const int | regina::vertexSplitMeeting [4][4][2]
| Lists which vertex splits meet which edges. More...
REGINA_API const int | regina::vertexSplitDefn [3][4]
| Lists the vertices which each vertex split splits. More...
REGINA_API const int | regina::vertexSplitPartner [3][4]
| Lists the second vertex with which each vertex is paired under each vertex split. More...
REGINA_API const char | regina::vertexSplitString [3][6]
| Contains strings describing which vertices each vertex split splits. More...
REGINA_API const NPerm4 | regina::triDiscArcs [4][3]
| Lists in consecutive order the directed normal arcs that form the boundary of each type of triangular normal disc. More...
REGINA_API const NPerm4 | regina::quadDiscArcs [3][4]
| Lists in consecutive order the directed normal arcs that form the boundary of each type of quadrilateral normal disc. More...
REGINA_API const NPerm4 | regina::octDiscArcs [3][8]
| Lists in consecutive order the directed normal arcs that form the boundary of each type of octagonal normal disc. More...

## Detailed Description

Normal surfaces in 3-manifold triangulations.

## Macro Definition Documentation

#define REGINA_NORMAL_SURFACE_FLAVOUR | ( |  | class_,
|  |  | id
| ) |  |

Value:
public: \
typedef NormalInfo<id> Info; \
enum { coordType = id }; \
inline virtual NNormalSurfaceVector* clone() const { \
return new class_(*this); \
} \
inline virtual bool allowsAlmostNormal() const { \
return Info::almostNormal; \
} \
inline virtual bool allowsSpun() const { \
return Info::spun; \
} \
inline virtual bool allowsOriented() const { \
return Info::oriented; \
}

Defines various constants, types and virtual functions for a subclass of NNormalSurfaceVector.

Every subclass of NNormalSurfaceVector must include REGINA_NORMAL_SURFACE_FLAVOUR at the beginning of the class definition.

This macro provides the class with:

- a compile-time enum constant coordType, which is equal to the corresponding NormalCoords constant;
- a typedef Info, which refers to the corresponding specialisation of the NormalInfo<> template;
- declarations and implementations of the virtual functions NNormalSurfaceVector::clone(), NNormalSurfaceVector::allowsAlmostNormal(), NNormalSurfaceVector::allowsSpun(), and NNormalSurfaceVector::allowsOriented().

Parameters

  class_ | the name of this subclass of NNormalSurfaceVector.
  id | the corresponding NNormalCoords constant.

#define REGINA_SURFACE_FILTER | ( |  | class_,
|  |  | id
| ) |  |

Value:
public: \
enum { filterType = id, filterID = id }; \
inline virtual SurfaceFilterType getFilterType() const { \
return id; \
} \
inline virtual SurfaceFilterType getFilterID() const { \
return id; \
} \
inline virtual std::string getFilterTypeName() const { \
return SurfaceFilterInfo<id>::name(); \
} \
inline virtual std::string getFilterName() const { \
return SurfaceFilterInfo<id>::name(); \
}
regina::SurfaceFilterType
SurfaceFilterType
Represents different types of filter classes that can be used to filter lists of normal surfaces in 3...
Definition: surfacefiltertype.h:60

Defines various constants, types and virtual functions for a descendant class of NSurfaceFilter.

Every descendant class of NSurfaceFilter must include REGINA_SURFACE_FILTER at the beginning of the class definition.

This macro provides the class with:

- a compile-time enum constant filterType, which is equal to the corresponding SurfaceFilterType constant;
- a deprecated compile-time enum constant filterID, which is identical to filterType;
- declarations and implementations of the virtual functions NSurfaceFilter::getFilterType() and NSurfaceFilter::getFilterTypeName();
- declarations and implementations of the deprecated virtual functions NSurfaceFilter::getFilterID() and NSurfaceFilter::getFilterName().

Parameters

  class_ | the name of this descendant class of NSurfaceFilter.
  id | the corresponding SurfaceFilterType constant.

## Typedef Documentation

typedef NewFunction1<NNormalSurfaceVector, size_t> regina::NewNormalSurfaceVector

A legacy typedef provided for backward compatibility only.

Deprecated:
  The old NewNormalSurfaceVector class has been redesigned as the more general template class NewFunction1, and moved into the header registryutils.h. This typedef is provided for backward compatibility, and will be removed in some future version of Regina.

typedef regina::Flags<NormalAlgFlags> regina::NormalAlg

A combination of flags for types of normal surface lists.

Python:
  This is present, and all values in the NormalAlgFlags enumeration type are treated as members of this NormalAlg class.

typedef regina::Flags<NormalListFlags> regina::NormalList

A combination of flags for types of normal surface lists.

Python:
  This is present, and all values in the NormalListFlags enumeration type are treated as members of this NormalList class.

## Enumeration Type Documentation

enum regina::NormalAlgFlags

Represents options and variants of algorithms for enumerating various types of normal surfaces.

These options are typically combined in a bitwise fashion using the NormalAlgs type, and then passed to enumeration routines such as NNormalSurfaceList::vertex().

Python:
  The values in this enumeration type are present, but they are treated by Python as NormalList objects (and they can be combined and/or queried as such). The underlying enumeration type is not exposed to Python.

Enumerator
NS_ALG_DEFAULT | An empty flag, indicating to an enumeration routine that it should use its default behaviour. The numeric value of this flag is zero (i.e., it has no effect when combined with other flags using bitwise OR).

NS_VERTEX_VIA_REDUCED

When enumerating in standard normal or almost normal coordinates, this flag indicates that the algorithm should first enumerate in quadrilateral or quadrilateral-octagon coordinates, and then expand this "reduced" solution set to the (typically larger) "standard" solution set.

This is typically much faster than a direct enumeration in standard normal or almost normal coordinates, and enumeration routines will use this option where possible unless explicitly requested not to (via the flag NS_VERTEX_STD_DIRECT).

For an explanation of this procedure, see B. A. Burton, "Converting between quadrilateral and standard solution sets in normal surface theory", Algebr. Geom. Topol. 9 (2009), 2121-2174.

This flag is incompatible with NS_VERTEX_STD_DIRECT.

NS_VERTEX_STD_DIRECT

When enumerating in standard normal or almost normal coordinates, this flag indicates that the algorithm should work directly in that coordinate system, and should not go via the "reduced" (quadrilateral or quadrilateral-octagon) coordinate system.

This is typically much slower than going via the reduced system, and users should only request this if they have a specialised need. See NS_VERTEX_VIA_REDUCED for further information.

This flag is incompatible with NS_VERTEX_VIA_REDUCED.

NS_VERTEX_TREE

When enumerating vertex normal surfaces, this flag indicates that the tree traversal algorithm should be used.

This algorithm is based on linear and integer programming techniques, and has many desirable properties including a relatively low overhead. Enumeration algorithms will use it if possible unless a different method is explicitly requested.

For details on the tree traversal algorithm, see B. A. Burton and M. Ozlen, "A tree traversal algorithm for decision problems in knot theory and 3-manifold topology", Algorithmica 65 (2013), pp. 772-801.

This flag is incompatible with NS_VERTEX_DD.

NS_VERTEX_DD

When enumerating vertex normal surfaces, this flag indicates that a modified double description method should be used.

This algorithm can suffer from a combinatorial explosion with larger problems, leading to extremely large time and memory footprints. Users should only request this if they have some specialised need.

For details on the modified double description method, see B. A. Burton, "Optimizing the double description method for normal surface enumeration", Mathematics of Computation 79 (2010), pp. 453-484.

This flag is incompatible with NS_VERTEX_TREE.

NS_HILBERT_PRIMAL

When enumerating fundamental normal surfaces, this flag indicates that the primal method should be used for enumerating a Hilbert basis.

The primal method is recommended, and enumeration algorithms will use it if possible unless a different method is explicitly requested. This method uses code from Normaliz for parts of its processing.

For details and comparisons of the various options for enumerating fundamental normal surfaces, see B. A. Burton, "Enumerating fundamental normal surfaces: Algorithms, experiments and invariants", to appear in ALENEX 2014: Proceedings of the Meeting on Algorithm Engineering & Experiments, arXiv:1111.7055.

This flag is incompatible with NS_HILBERT_DUAL, NS_HILBERT_CD and NS_HILBERT_FULLCONE.

NS_HILBERT_DUAL

When enumerating fundamental normal surfaces, this flag indicates that the dual method should be used for enumerating a Hilbert basis.

The dual method is fast (like the primal method), but its performance is highly variable; for this reason the primal method is recommended instead. This method does not make use of Normaliz, and is the recommended method for situations in which Normaliz is not available for some reason.

For details and comparisons of the various options for enumerating fundamental normal surfaces, see B. A. Burton, "Enumerating fundamental normal surfaces: Algorithms, experiments and invariants", to appear in ALENEX 2014: Proceedings of the Meeting on Algorithm Engineering & Experiments, arXiv:1111.7055.

This flag is incompatible with NS_HILBERT_PRIMAL, NS_HILBERT_CD and NS_HILBERT_FULLCONE.

NS_HILBERT_CD

When enumerating fundamental normal surfaces, this flag indicates that a modified Contejean-Devie procedure should be used for enumerating a Hilbert basis.

The Contejean-Devie procedure is typically much slower than either the primal or dual method, and users should only request it if they have some specialised need.

For details and comparisons of the various options for enumerating fundamental normal surfaces, see B. A. Burton, "Enumerating fundamental normal surfaces: Algorithms, experiments and invariants", to appear in ALENEX 2014: Proceedings of the Meeting on Algorithm Engineering & Experiments, arXiv:1111.7055.

This flag is incompatible with NS_HILBERT_PRIMAL, NS_HILBERT_DUAL and NS_HILBERT_FULLCONE.

NS_HILBERT_FULLCONE

When enumerating fundamental normal surfaces, this flag indicates that a Hilbert basis for the full solution cone should be constructed, and additional combinatorial constraints (such as the quadrilateral constraints) should only be enforced as the final step.

If you are only enumerating properly embedded surfaces then this procedure extremely slow, and users should only request it if they have some specialised need.

For details and comparisons of the various options for enumerating fundamental normal surfaces, see B. A. Burton, "Enumerating fundamental normal surfaces: Algorithms, experiments and invariants", to appear in ALENEX 2014: Proceedings of the Meeting on Algorithm Engineering & Experiments, arXiv:1111.7055.

This flag is incompatible with NS_HILBERT_PRIMAL, NS_HILBERT_DUAL and NS_HILBERT_CD.

NS_ALG_LEGACY | Indicates that a normal surface list was enumerated using an older version of Regina (4.93 or earlier). These older versions did not retain details of the algorithm used to build each list, and so in such cases no further algorithmic information is available. If this flag is passed to an enumeration algorithm, it will be ignored.
NS_ALG_CUSTOM | Indicates that a normal surface list was built using a customised algorithm. In such cases, no further details on the algorithm are available. If this flag is passed to an enumeration algorithm, it will be ignored.

enum regina::NormalCoords

Represents different coordinate systems that can be used for enumerating and displaying normal surfaces.

IDs 0-9999 are reserved for future use by Regina. If you are extending Regina to include your own coordinate system, you should choose an ID >= 10000.

Enumerator
NS_STANDARD | Represents standard triangle-quadrilateral coordinates for normal surfaces.
NS_QUAD | Represents quadrilateral coordinates for normal surfaces. For details, see "Normal surface Q-theory", Jeffrey L. Tollefson, Pacific J. Math. 183 (1998), no. 2, 359–374.

NS_AN_LEGACY

Indicates that a list of almost normal surfaces was created using Regina 4.5.1 or earlier, where surfaces with more than one octagon of the same type were stripped out of the final solution set.

As of Regina 4.6 such surfaces are now included in the solution set, since we need them if we wish to enumerate all almost normal surfaces (not just the vertex almost normal surfaces).

This coordinate system is only used with legacy data files; new vectors and lists cannot be created in this coordinate system. The underlying coordinates are identical to those of NS_AN_STANDARD.

NS_AN_QUAD_OCT | Represents quadrilateral-octagon coordinates for octagonal almost normal surfaces. For details, see "Quadrilateral-octagon coordinates for almost normal surfaces", Benjamin A. Burton, Experiment. Math. 19 (2010), 285-315.
NS_AN_STANDARD | Represents standard triangle-quadrilateral-octagon coordinates for octagonal almost normal surfaces.
NS_EDGE_WEIGHT | Represents edge weight coordinates for normal surfaces. This coordinate system is for display only; surface vectors and lists cannot be created in this coordinate system.
NS_TRIANGLE_ARCS | Represents triangle arc coordinates for normal surfaces. This coordinate system is for display only; surface vectors and lists cannot be created in this coordinate system.

NS_FACE_ARCS

A deprecated alias for NS_TRIANGLE_ARCS.

This represents triangle arc coordinates for normal surfaces. See NS_TRIANGLE_ARCS for further details.

Deprecated:
  This constant will be removed in a future version of Regina. Please use NS_TRIANGLE_ARCS instead.

NS_ORIENTED | Represents standard triangle-quadrilateral coordinates for transversely oriented normal surfaces.
NS_ORIENTED_QUAD | Represents quadrilateral coordinates for transversely oriented normal surfaces.

enum regina::NormalListFlags

Represents different lists of normal surfaces that might be constructed for a given triangulation.

The NormalList enumeration refers to the contents of the list, whereas the NormalAlgFlags enumeration refers to the algorithm used to build it.

Python:
  The values in this enumeration type are present, but they are treated by Python as NormalList objects (and they can be combined and/or queried as such). The underlying enumeration type is not exposed to Python.

Enumerator
NS_LIST_DEFAULT | An empty flag, indicating to an enumeration routine that it should use its default behaviour. The numeric value of this flag is zero (i.e., it has no effect when combined with other flags using bitwise OR).
NS_EMBEDDED_ONLY | Indicates that this list is restricted to properly embedded surfaces only. This flag is incompatible with NS_IMMERSED_SINGULAR.

NS_IMMERSED_SINGULAR

Indicates that the scope of this list includes not just properly embedded surfaces, but also immersed and/or branched surfaces.

This is no guarantee that the list contains immersed and/or branched surfaces; it merely states that such surfaces have not been explicitly excluded (in particular, the quadrilateral constraints have not been enforced).

This flag is incompatible with NS_EMBEDDED_ONLY.

NS_VERTEX | Indicates a list of all vertex normal surfaces, with respect to the particular normal coordinate system used by the list. This flag is incompatible with NS_FUNDAMENTAL.
NS_FUNDAMENTAL | Indicates a list of all fundamental normal surfaces, with respect to the particular normal coordinate system used by the list. This flag is incompatible with NS_VERTEX.

NS_LEGACY

Indicates a list that was constructed using an old version of Regina (4.93 or earlier).

These older versions did not retain details of how each list was constructed, beyond whether immersed and/or singular surfaces were included. Therefore no information is available for such lists, other than the presence or absence of the NS_EMBEDDED_ONLY and/or NS_IMMERSED_SINGULAR flags.

If this flag is passed to an enumeration routine, it will be ignored.

NS_CUSTOM | Indicates some other type of list, typically hand-crafted by the user or built by some customised algorithm. If this flag is passed to an enumeration routine, it will be ignored.

enum regina::SurfaceFilterType

Represents different types of filter classes that can be used to filter lists of normal surfaces in 3-manifold triangulations.

IDs 0-9999 are reserved for future use by Regina. If you are extending Regina to include your own filter class, you should choose an ID >= 10000.

Enumerator
NS_FILTER_DEFAULT | Represents the NSurfaceFilter class: a do-nothing filter that accepts any normal surface.
NS_FILTER_PROPERTIES | Represents the NSurfaceFilterProperties subclass: a filter that examines simple properties of a normal surface.
NS_FILTER_COMBINATION | Represents the NSurfaceFilterCombination subclass: a filter that combines other filters using boolean AND or OR.

## Function Documentation

REGINA_API bool regina::discOrientationFollowsEdge | ( | int | discType,
|  | int | vertex,
|  | int | edgeStart,
|  | int | edgeEnd
| ) |  |

Determines whether or not the natural boundary orientation of a normal disc of the given type follows the given directed normal arc.

Natural boundary orientation is defined by arrays triDiscArcs, quadDiscArcs and octDiscArcs.

Precondition
  The given normal arc lies on a normal disc of the given type.

Parameters

  discType | the normal disc type under consideration; this should be between 0 and 9 inclusive, as described by the NDiscSpec class notes.
  vertex | the vertex about which the normal arc runs.
  edgeStart | the start vertex of the edge to which the normal arc is parallel.
  edgeEnd | the end vertex of the edge to which the normal arc is parallel.

template<typename FunctionObject >

FunctionObject::ReturnType regina::forCoords | ( | NormalCoords | coords,
|  | FunctionObject | func,
|  | typename FunctionObject::ReturnType | defaultReturn
| ) |  |

Allows the user to call a template function whose template parameter matches a given value of NormalCoords, which is not known until runtime.

In essence, this routine contains a switch/case statement that runs through all possible coordinate sytems.

The advantages of this routine are that (i) the user does not need to repeatedly type such switch/case statements themselves; and (ii) if a new coordinate system is added then only a small amount of code needs to be extended to incorporate it.

This function can only work with coordinate systems in which you can create and store normal surfaces. All other coordinate systems are considered invalid for our purposes here.

In detail: the function object func must define a templated unary bracket operator, so that `func(NormalInfo<c>)` is defined for any valid NormalCoords enum value c. Then, when the user calls `forCoords(coords, func, defaultReturn)`, this routine will call `func(NormalInfo<coords>)` and pass back the corresponding return value. If coords does not denote a valid coordinate system as described above, then forCoords() will pass back defaultReturn instead.

There is also a two-argument variant of forCoords() that works with void functions.

Precondition
  The function object must have a typedef ReturnType indicating the return type of the corresponding templated unary bracket operator. Inheriting from Returns<...> is a convenient way to ensure this.

Python:
  Not present.

Parameters

  coords | the given normal coordinate system.
  func | the function object whose unary bracket operator we will call with a NormalInfo<coords> object.
  defaultReturn | the value to return if the given coordinate system is invalid.

Returns
  the return value from the corresponding unary bracket operator of func, or defaultReturn if the given coordinate system is invalid.

template<typename VoidFunctionObject >

void regina::forCoords | ( | NormalCoords | coords,
|  | VoidFunctionObject | func
| ) |  |

Allows the user to call a template function whose template parameter matches a given value of NormalCoords, which is not known until runtime.

In essence, this routine contains a switch/case statement that runs through all possible coordinate sytems.

The advantages of this routine are that (i) the user does not need to repeatedly type such switch/case statements themselves; and (ii) if a new coordinate system is added then only a small amount of code needs to be extended to incorporate it.

This function can only work with coordinate systems in which you can create and store normal surfaces. All other coordinate systems are considered invalid for our purposes here.

In detail: the function object func must define a templated unary bracket operator, so that `func(NormalInfo<c>)` is defined for any valid NormalCoords enum value c. Then, when the user calls `forCoords(coords, func)`, this routine will call `func(NormalInfo<coords>)` in turn. If coords does not denote a valid coordinate system as described above, then forCoords() will do nothing.

There is also a three-argument variant of forCoords() that works with functions with return values.

Python:
  Not present.

Parameters

  coords | the given normal coordinate system.
  func | the function object whose unary bracket operator we will call with a NormalInfo<coords> object.

template<typename FunctionObject >

FunctionObject::ReturnType regina::forFilter | ( | SurfaceFilterType | filter,
|  | FunctionObject | func,
|  | typename FunctionObject::ReturnType | defaultReturn
| ) |  |

Allows the user to call a template function whose template parameter matches a given value of SurfaceFilterType, which is not known until runtime.

In essence, this routine contains a switch/case statement that runs through all possible normal surface filter types.

The advantages of this routine are that (i) the user does not need to repeatedly type such switch/case statements themselves; and (ii) if a new filter type is added then only a small amount of code needs to be extended to incorporate it.

In detail: the function object func must define a templated unary bracket operator, so that `func(SurfaceFilterInfo<t>)` is defined for any valid SurfaceFilterType enum value t. Then, when the user calls `forFilter(filter, func, defaultReturn)`, this routine will call `func(SurfaceFilterInfo<filter>)` and pass back the corresponding return value. If filter does not denote a valid filter type, then forFilter() will pass back defaultReturn instead.

There is also a two-argument variant of forFilter() that works with void functions.

Precondition
  The function object must have a typedef ReturnType indicating the return type of the corresponding templated unary bracket operator. Inheriting from Returns<...> is a convenient way to ensure this.

Python:
  Not present.

Parameters

  filter | the given type of normal surface filter.
  func | the function object whose unary bracket operator we will call with a SurfaceFilterInfo<filter> object.
  defaultReturn | the value to return if the given filter type is not valid.

Returns
  the return value from the corresponding unary bracket operator of func, or defaultReturn if the given filter type is not valid.

template<typename VoidFunctionObject >

void regina::forFilter | ( | SurfaceFilterType | filter,
|  | VoidFunctionObject | func
| ) |  |

Allows the user to call a template function whose template parameter matches a given value of SurfaceFilterType, which is not known until runtime.

In essence, this routine contains a switch/case statement that runs through all possible normal surface filter types.

The advantages of this routine are that (i) the user does not need to repeatedly type such switch/case statements themselves; and (ii) if a new filter type is added then only a small amount of code needs to be extended to incorporate it.

In detail: the function object func must define a templated unary bracket operator, so that `func(SurfaceFilterInfo<t>)` is defined for any valid SurfaceFilterType enum value t. Then, when the user calls `forFilter(filter, func)`, this routine will call `func(SurfaceFilterInfo<filter>)` in turn. If filter does not denote a valid filter type, then forFilter() will do nothing.

There is also a three-argument variant of forFilter() that works with functions with return values.

Python:
  Not present.

Parameters

  filter | the given type of normal surface filter.
  func | the function object whose unary bracket operator we will call with a SurfaceFilterInfo<filter> object.

template<typename FunctionObject >

FunctionObject::ReturnType regina::forFlavour | ( | NormalCoords | coords,
|  | FunctionObject | func,
|  | typename FunctionObject::ReturnType | defaultReturn
| ) |  |

inline

A deprecated alias for the registry-based template function forCoords().

See forCoords() for further details.

template<typename VoidFunctionObject >

void regina::forFlavour | ( | NormalCoords | coords,
|  | VoidFunctionObject | func
| ) |  |

inline

A deprecated alias for the registry-based template function forCoords().

See forCoords() for further details.

REGINA_API NEnumConstraintList* regina::makeEmbeddedConstraints | ( | NTriangulation * | triangulation,
|  | NormalCoords | coords
| ) |  |

Creates a new set of validity constraints representing the condition that normal surfaces be embedded.

The validity constraints will be expressed relative to the given coordinate system.

Python:
  Not present.

Parameters

  triangulation | the triangulation upon which these validity constraints will be based.
  coords | the coordinate system to be used.

Returns
  a newly allocated set of constraints.

REGINA_API NMatrixInt* regina::makeMatchingEquations | ( | NTriangulation * | triangulation,
|  | NormalCoords | coords
| ) |  |

Creates a new set of normal surface matching equations for the given triangulation using the given coordinate system.

The returned matrix will be newly allocated and its destruction will be the responsibility of the caller of this routine.

Each equation will be represented as a row of the matrix. Each column of the matrix represents a coordinate in the given coordinate system.

Parameters

  triangulation | the triangulation upon which these matching equations will be based.
  coords | the coordinate system to be used.

Returns
  a newly allocated set of matching equations.

REGINA_API NNormalSurfaceVector* regina::makeZeroVector | ( | const NTriangulation * | triangulation,
|  | NormalCoords | coords
| ) |  |

Returns a new normal surface vector of the appropriate length for the given triangulation and the given coordinate system.

All elements of this vector will be initialised to zero.

The new vector will be of the subclass of NNormalSurfaceVector corresponding to the given coordinate system. The caller of this routine is responsible for destroying the new vector.

Python:
  Not present.

Parameters

  triangulation | the triangulation upon which the underlying coordinate system is based.
  coords | the coordinate system to be used.

Returns
  a new zero vector of the correct class and length.

REGINA_API bool regina::numberDiscsAwayFromVertex | ( | int | discType,
|  | int | vertex
| ) |  |

Determines whether or not normal discs of the given type are numbered away from the given vertex.

Parameters

  discType | the normal disc type under consideration; this should be between 0 and 9 inclusive, as described by the NDiscSpec class notes.
  vertex | the vertex under consideration; this should be between 0 and 3 inclusive.

Returns
  `true` if normal discs of the given type are numbered away from the given vertex, or `false` if they are numbered towards the given vertex.

REGINA_API std::ostream& regina::operator<< | ( | std::ostream & | out,
|  | const NPrismSpec & | spec
| ) |  |

Writes the given prism specifier to the given output stream.

The prism specifier will be written as a pair `(tetIndex, edge)`.

Parameters

  out | the output stream to which to write.
  spec | the prism specifier to write.

Returns
  a reference to out.

REGINA_API std::ostream& regina::operator<< | ( | std::ostream & | out,
|  | const NDiscSpec & | spec
| ) |  |

Writes the given disc specifier to the given output stream.

The disc specifier will be written as a triple `(tetIndex, type, number)`.

Parameters

  out | the output stream to which to write.
  spec | the disc specifier to write.

Returns
  a reference to out.

std::ostream & regina::operator<< | ( | std::ostream & | out,
|  | const NDiscType & | type
| ) |  |

inline

Writes the given disc type to the given output stream.

The disc type will be written as a pair `(tetIndex, type)`.

Parameters

  out | the output stream to which to write.
  type | the disc type to write.

Returns
  a reference to the given output stream.

NormalList regina::operator| | ( | NormalListFlags | lhs,
|  | NormalListFlags | rhs
| ) |  |

inline

Returns the bitwise OR of the two given flags.

Parameters

  lhs | the first flag to combine.
  rhs | the second flag to combine.

Returns
  the combination of both flags.

NormalAlg regina::operator| | ( | NormalAlgFlags | lhs,
|  | NormalAlgFlags | rhs
| ) |  |

inline

Returns the bitwise OR of the two given flags.

Parameters

  lhs | the first flag to combine.
  rhs | the second flag to combine.

Returns
  the combination of both flags.

## Variable Documentation

REGINA_API const NPerm4 regina::octDiscArcs[3][8]

Lists in consecutive order the directed normal arcs that form the boundary of each type of octagonal normal disc.

Each permutation p represents an arc about vertex `p[0]` parallel to the directed edge from `p[1]` to `p[2]`.

Array `octDiscArcs[i]` lists the boundary arcs of the octagonal disc of type i. See NNormalSurface::getOctCoord() for further details.

Note that permutation `octDiscArcs[i][j]` will be even precisely when `j` is 0, 1, 4 or 5.

C++:
  This array is replaced by a macro `octDiscArcs(discType, arcIndex)` that essentially looks up the corresponding array. This is necessary because of a bug in gcc 2.95.

REGINA_API const NPerm4 regina::quadDiscArcs[3][4]

Lists in consecutive order the directed normal arcs that form the boundary of each type of quadrilateral normal disc.

Each permutation p represents an arc about vertex `p[0]` parallel to the directed edge from `p[1]` to `p[2]`.

Array `quadDiscArcs[i]` lists the boundary arcs of the quadrilateral disc of type i. See NNormalSurface::getQuadCoord() for further details.

Note that permutation `quadDiscArcs[i][j]` will be even precisely when `j` is even.

C++:
  This array is replaced by a macro `quadDiscArcs(discType, arcIndex)` that essentially looks up the corresponding array. This is necessary because of a bug in gcc 2.95.

REGINA_API const NPerm4 regina::triDiscArcs[4][3]

Lists in consecutive order the directed normal arcs that form the boundary of each type of triangular normal disc.

Each permutation p represents an arc about vertex `p[0]` parallel to the directed edge from `p[1]` to `p[2]`.

Array `triDiscArcs[i]` lists the boundary arcs of the triangular disc of type i. See NNormalSurface::getTriangleCoord() for further details.

Note that every permutation in this array is even.

C++:
  This array is replaced by a macro `triDiscArcs(discType, arcIndex)` that essentially looks up the corresponding array. This is necessary because of a bug in gcc 2.95.

REGINA_API const int regina::vertexSplit[4][4]

Lists which vertex splits separate which pairs of vertices.

There are three vertex splits, numbered 0,1,2. Each vertex split separates the four tetrahedron vertices 0,1,2,3 into two pairs. `vertexSplit[i][j]` is the number of the vertex split that keeps vertices `i` and `j` together.

It is guaranteed that vertex split i will keep the vertices of edge i together (and will therefore also keep the vertices of edge 5-i together).

REGINA_API const int regina::vertexSplitDefn[3][4]

Lists the vertices which each vertex split splits.

See vertexSplit for details on what a vertex split is. Vertex split number `i` splits the vertex pairs `vertexSplitDefn[i][0,1]` and `vertexSplitDefn[i][2,3]`.

It is guaranteed that:

- `vertexSplitDefn[i][0] < vertexSplitDefn[i][1]`;
- `vertexSplitDefn[i][2] < vertexSplitDefn[i][3]`;
- `vertexSplitDefn[i][0] < vertexSplitDefn[i][2]`.

REGINA_API const int regina::vertexSplitMeeting[4][4][2]

Lists which vertex splits meet which edges.

See vertexSplit for details on what a vertex split is. `vertexSplitMeeting[i][j][0,1]` are the numbers of the two vertex splits that meet the edge joining tetrahedron vertices `i` and `j`.

REGINA_API const int regina::vertexSplitPartner[3][4]

Lists the second vertex with which each vertex is paired under each vertex split.

See vertexSplit for details on what a vertex split is. Vertex split number `i` pairs vertex `v` with vertex `vertexSplitPartner[i][v]`.

REGINA_API const char regina::vertexSplitString[3][6]

Contains strings describing which vertices each vertex split splits.

See vertexSplit for details on what a vertex split is. The string describing vertex split number `i` is `vertexSplitString[i]` and is of the form `02/13`, which in this case is the vertex split that splits vertices 0,2 from vertices 1,3.

Copyright © 1999-2013, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@debian.org).