Normal Hypersurfaces

Normal hypersurfaces in 4-manifold triangulations. More...

Classes
class	regina::HyperEncoding
	Indicates precisely how a normal hypersurface within a 4-manifold triangulation is encoded by an integer vector. More...
class	regina::HyperInfo
	A class used to query general information about different normal hypersurface coordinate systems. More...
class	regina::NormalHypersurface
	Represents a single normal hypersurface in a 4-manifold triangulation. More...
class	regina::NormalHypersurfaces
	A collection of normal hypersurfaces in a 4-manifold triangulation. More...

Typedefs
using	regina::HyperList = regina::Flags< HyperListFlags >
	A combination of flags for types of normal hypersurface lists. More...
using	regina::HyperAlg = regina::Flags< HyperAlgFlags >
	A combination of flags for normal hypersurface enumeration algorithms. More...

Enumerations
enum	regina::HyperCoords { regina::HS_STANDARD = 0 , regina::HS_PRISM = 1 , regina::HS_EDGE_WEIGHT = 200 }
	Represents different coordinate systems that can be used for enumerating and/or displaying normal hypersurfaces within 4-manifold triangulations. More...
enum	regina::HyperListFlags {   regina::HS_LIST_DEFAULT = 0x0000 , regina::HS_EMBEDDED_ONLY = 0x0001 , regina::HS_IMMERSED_SINGULAR = 0x0002 , regina::HS_VERTEX = 0x0004 ,   regina::HS_FUNDAMENTAL = 0x0008 , regina::HS_LEGACY = 0x4000 , regina::HS_CUSTOM = 0x8000 }
	Represents different lists of normal hypersurfaces that might be constructed for a given 4-manifold triangulation. More...
enum	regina::HyperAlgFlags {   regina::HS_ALG_DEFAULT = 0x0000 , regina::HS_VERTEX_DD = 0x0020 , regina::HS_HILBERT_PRIMAL = 0x0100 , regina::HS_HILBERT_DUAL = 0x0200 ,   regina::HS_ALG_LEGACY = 0x4000 , regina::HS_ALG_CUSTOM = 0x8000 }
	Represents options and variants of algorithms for enumerating various types of normal hypersurfaces in 4-manifold triangulations. More...

Functions
HyperList	regina::operator| (HyperListFlags lhs, HyperListFlags rhs)
	Returns the bitwise OR of the two given flags. More...
HyperAlg	regina::operator| (HyperAlgFlags lhs, HyperAlgFlags rhs)
	Returns the bitwise OR of the two given flags. More...
void	regina::swap (NormalHypersurface &a, NormalHypersurface &b) noexcept
	Swaps the contents of the given normal hypersurfaces. More...
void	regina::swap (NormalHypersurfaces &lhs, NormalHypersurfaces &rhs)
	Swaps the contents of the two given lists. More...
MatrixInt	regina::makeMatchingEquations (const Triangulation< 4 > &triangulation, HyperCoords coords)
	Generates the set of normal hypersurface matching equations for the given triangulation using the given coordinate system. More...
ValidityConstraints	regina::makeEmbeddedConstraints (const Triangulation< 4 > &triangulation, HyperCoords coords)
	Generates the validity constraints representing the condition that normal hypersurfaces be embedded. More...

Detailed Description

Normal hypersurfaces in 4-manifold triangulations.

Typedef Documentation

HyperAlg

using regina::HyperAlg = typedef regina::Flags<HyperAlgFlags>

A combination of flags for normal hypersurface enumeration algorithms.

If a function requires a HyperAlg object as an argument, you can pass a single HyperAlgFlags constant, or a combination of such constants using the bitwise OR operator, or empty braces {} to indicate no flags at all.

HyperList

using regina::HyperList = typedef regina::Flags<HyperListFlags>

A combination of flags for types of normal hypersurface lists.

If a function requires a HyperList object as an argument, you can pass a single HyperListFlags constant, or a combination of such constants using the bitwise OR operator, or empty braces {} to indicate no flags at all.

Enumeration Type Documentation

HyperAlgFlags

enum regina::HyperAlgFlags

Represents options and variants of algorithms for enumerating various types of normal hypersurfaces in 4-manifold triangulations.

These options can be combined using the bitwise OR operator, and then passed to enumeration routines such as the NormalHypersurfaces class constructor.

Enumerator
HS_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).
HS_VERTEX_DD	When enumerating vertex normal hypersurfaces, 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. Having said that: this is the only algorithm that Regina currently supports for 4-dimensional vertex enumeration (unlike the 3-dimensional case, where several alternative algorithms are available). Therefore Regina will use the double description method regardless. Alternative algorithms will be implemented in future versions of Regina. 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.
HS_HILBERT_PRIMAL	When enumerating fundamental normal hypersurfaces, 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", ALENEX 2014: Proceedings of the Meeting on Algorithm Engineering & Experiments, SIAM, 2014, pp. 112-124. This flag is incompatible with HS_HILBERT_DUAL.
HS_HILBERT_DUAL	When enumerating fundamental normal hypersurfaces, 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", ALENEX 2014: Proceedings of the Meeting on Algorithm Engineering & Experiments, SIAM, 2014, pp. 112-124. This flag is incompatible with HS_HILBERT_PRIMAL.
HS_ALG_LEGACY	Indicates that a normal hypersurface list was enumerated using an older prerelease version of the 4-manifolds code (prior to Regina 5.0). These prerelease 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.
HS_ALG_CUSTOM	Indicates that a normal hypersurface 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.

HyperCoords

enum regina::HyperCoords

Represents different coordinate systems that can be used for enumerating and/or displaying normal hypersurfaces within 4-manifold triangulations.

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
HS_STANDARD	Represents standard tetrahedron-prism coordinates for normal hypersurfaces. Regina can both enumerate and view hypersurfaces in this coordinate system.
HS_PRISM	Represents prism coordinates for normal hypersurfaces. Regina can both enumerate and view hypersurfaces in this coordinate system.
HS_EDGE_WEIGHT	Represents edge weight coordinates for normal hypersurfaces. This coordinate system is for display only: Regina can view hypersurfaces in this coordinate system, but it cannot use it to enumerate or create hypersurfaces.

HyperListFlags

enum regina::HyperListFlags

Represents different lists of normal hypersurfaces that might be constructed for a given 4-manifold triangulation.

The HyperList enumeration refers to the contents of the list, whereas the HyperAlgFlags enumeration refers to the algorithm used to build it.

These flags can be combined using the bitwise OR operator, and then passed to enumeration routines such as the NormalHypersurfaces class constructor.

Enumerator
HS_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).
HS_EMBEDDED_ONLY	Indicates that this list is restricted to properly embedded hypersurfaces only. This flag is incompatible with HS_IMMERSED_SINGULAR.
HS_IMMERSED_SINGULAR	Indicates that the scope of this list includes not just properly embedded hypersurfaces, but also immersed and/or branched hypersurfaces. This is no guarantee that the list contains immersed and/or branched hypersurfaces; it merely states that such hypersurfaces have not been explicitly excluded (in particular, the prism constraints have not been enforced). This flag is incompatible with HS_EMBEDDED_ONLY.
HS_VERTEX	Indicates a list of all vertex normal hypersurfaces, with respect to the particular normal coordinate system used by the list. This flag is incompatible with HS_FUNDAMENTAL.
HS_FUNDAMENTAL	Indicates a list of all fundamental normal hypersurfaces, with respect to the particular normal coordinate system used by the list. This flag is incompatible with HS_VERTEX.
HS_LEGACY	Indicates a list that was constructed using an older prerelease version of the 4-manifolds code (prior to Regina 5.0). These prerelease versions did not retain details of how each list was constructed, beyond whether immersed and/or singular hypersurfaces were included. Therefore no information is available for such lists, other than the presence or absence of the HS_EMBEDDED_ONLY and/or HS_IMMERSED_SINGULAR flags. If this flag is passed to an enumeration routine, it will be ignored.
HS_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.

Function Documentation

makeEmbeddedConstraints()

ValidityConstraints regina::makeEmbeddedConstraints	(	const Triangulation< 4 > &	triangulation,
		HyperCoords	coords
	)

Generates the validity constraints representing the condition that normal hypersurfaces be embedded.

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

These are the constraints that will be used when enumerating embedded hypersurfaces in the given coordinate system (i.e., when the default HS_EMBEDDED_ONLY flag is used). They will not be used when the enumeration allows for immersed and/or singular hypersurfaces.

Parameters

triangulation	the triangulation upon which these validity constraints will be based.
coords	the coordinate system to be used; this must be one of the predefined coordinate system constants in NormalHypersurfaces.

Returns

the set of validity constraints.

makeMatchingEquations()

MatrixInt regina::makeMatchingEquations	(	const Triangulation< 4 > &	triangulation,
		HyperCoords	coords
	)

Generates the set of normal hypersurface matching equations for the given triangulation using the given coordinate system.

These are the matching equations that will be used when enumerating normal hypersurfaces in the coordinate system coords.

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

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.

Parameters

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

Returns

the resulting set of matching equations.

operator|() [1/2]

HyperAlg regina::operator| ( HyperAlgFlags  lhs, HyperAlgFlags  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.

operator|() [2/2]

HyperList regina::operator| ( HyperListFlags  lhs, HyperListFlags  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.

swap() [1/2]

void regina::swap ( NormalHypersurface &  a, NormalHypersurface &  b  )

inlinenoexcept

Swaps the contents of the given normal hypersurfaces.

This is a fast (constant time) operation.

This global routine simply calls NormalHypersurface::swap(); it is provided so that NormalHypersurface meets the C++ Swappable requirements.

Parameters

a	the first normal hypersurface whose contents should be swapped.
b	the second normal hypersurface whose contents should be swapped.

swap() [2/2]

void regina::swap ( NormalHypersurfaces &  lhs, NormalHypersurfaces &  rhs  )

inline

Swaps the contents of the two given lists.

This global routine simply calls NormalHypersurfaces::swap(); it is provided so that NormalHypersurfaces meets the C++ Swappable requirements.

See NormalHypersurfaces::swap() for more details.

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

lhs	the list whose contents should be swapped with rhs.
rhs	the list whose contents should be swapped with lhs.