Normal Hypersurfaces

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

## Classes

class | regina::HSVectorStandard
| A normal hypersurface vector using standard tetrahedron-prism coordinates. More...
class | regina::MatrixIntDomain< T >
| Represents a matrix of elements from a given integral domain T. More...
struct | regina::HyperInfo< coordType >
| A template that stores information about a particular normal hypersurface coordinate system. More...
class | regina::NormalHypersurfaceVector
| Stores the vector of a single normal hypersurface in a 4-manifold triangulation. More...
class | regina::NormalHypersurface
| Represents a single normal hypersurface in a 4-manifold triangulation. More...
class | regina::NormalHypersurfaces
| A packet representing a collection of normal hypersurfaces in a 4-manifold triangulation. More...
class | regina::XMLNormalHypersurfaceReader
| An XML element reader that reads a single normal hypersurface in a 4-manifold triangulation. More...
class | regina::XMLNormalHypersurfacesReader
| An XML packet reader that reads a single normal hypersurface list. More...

## Macros

#define | REGINA_NORMAL_HYPERSURFACE_FLAVOUR(class_, id, superclass)
| Defines various constants, types and virtual functions for a subclass of NormalHypersurfaceVector. More...

## Typedefs

typedef HSVectorStandard | regina::NNormalHypersurfaceVectorStandard
| Deprecated typedef for backward compatibility. More...
typedef regina::Flags< HyperListFlags > | regina::HyperList
| A combination of flags for types of normal hypersurface lists. More...
typedef regina::Flags< HyperAlgFlags > | regina::HyperAlg
| A combination of flags for types of normal surface lists. More...
typedef MatrixIntDomain< Integer > | regina::MatrixInt
| A matrix of arbitrary-precision integers. More...
typedef NormalHypersurfaceVector | regina::NNormalHypersurfaceVector
| Deprecated typedef for backward compatibility. More...
typedef NormalHypersurface | regina::NNormalHypersurface
| Deprecated typedef for backward compatibility. More...
typedef NormalHypersurfaces | regina::NNormalHypersurfaceList
| Deprecated typedef for backward compatibility. 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 displaying normal hypersurface 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

template<typename FunctionObject , typename... Args>
ReturnsTraits< FunctionObject >::ReturnType | regina::forCoords (HyperCoords coords, FunctionObject &&func, typename ReturnsTraits< FunctionObject >::ReturnType defaultReturn, Args &&... args)
| Allows the user to call a template function whose template parameter matches a given value of HyperCoords, which is not known until runtime. More...
template<typename FunctionObject , typename... Args>
ReturnsTraits< FunctionObject >::Void | regina::forCoords (HyperCoords coords, FunctionObject &&func, Args &&... args)
| Allows the user to call a template function whose template parameter matches a given value of HyperCoords, which is not known until runtime. More...
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...
NormalHypersurfaceVector * | regina::makeZeroVector (const Triangulation< 4 > *triangulation, HyperCoords coords)
| Returns a new normal hypersurface vector of the appropriate length for the given triangulation and the given coordinate system. More...
MatrixInt * | regina::makeMatchingEquations (const Triangulation< 4 > *triangulation, HyperCoords coords)
| Creates a new set of normal hypersurface matching equations for the given triangulation using the given coordinate system. More...
EnumConstraints * | regina::makeEmbeddedConstraints (const Triangulation< 4 > *triangulation, HyperCoords coords)
| Creates a new set of validity constraints representing the condition that normal hypersurfaces be embedded. More...

## Detailed Description

Normal hypersurfaces in 4-manifold triangulations.

## Macro Definition Documentation

## REGINA_NORMAL_HYPERSURFACE_FLAVOUR

#define REGINA_NORMAL_HYPERSURFACE_FLAVOUR | ( |  | class_,
|  |  | id,
|  |  | superclass
| ) |  |

Value:
public: \
typedef HyperInfo<id> Info; \
static constexpr const HyperCoords coordsID = id; \
inline class_(const class_& cloneMe) : \
superclass(cloneMe.coords()) {} \
inline virtual NormalHypersurfaceVector* clone() const { \
return new class_(*this); \
}
regina::HyperCoords
HyperCoords
Represents different coordinate systems that can be used for enumerating and displaying normal hypers...
Definition: hypercoords.h:60

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

Every subclass of NormalHypersurfaceVector must include REGINA_NORMAL_HYPERSURFACE_FLAVOUR at the beginning of the class definition.

This macro provides the class with:

- a compile-time enum constant coordsID, which is equal to the corresponding HyperCoords constant;
- a typedef Info, which refers to the corresponding specialisation of the HyperInfo<> tempate;
- a copy constructor that takes a vector of the same subclass;
- declarations and implementations of the virtual function NormalHypersurfaceVector::clone().

Parameters

  class_ | the name of this subclass of NormalHypersurfaceVector.
  id | the corresponding NNormalCoords constant.
  superclass | the vector class from which class_ is derived. This is typically NormalHypersurfaceVector, though in some cases (e.g., prism coordinates) it may be different.

## Typedef Documentation

## HyperAlg

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

A combination of flags for types of normal surface lists.

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

## HyperList

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

A combination of flags for types of normal hypersurface lists.

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

## MatrixInt

typedef MatrixIntDomain< Integer > regina::MatrixInt

A matrix of arbitrary-precision integers.

This is the most common class used by Regina when running algebraic algorithms over integer matrices. Since the underlying type is Regina's Integer class, calculations will be exact regardless of how large the integers become.

Python:
  This represents the class MatrixIntDomain<Integer>, which inherits from Matrix<Integer> and MatrixRing<Integer>. Most but not all inherited functions are implemented; see the individual members' documentation for exceptions where they arise.

## NNormalHypersurface

typedef NormalHypersurface regina::NNormalHypersurface

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NNormalHypersurface has now been renamed to NormalHypersurface.

## NNormalHypersurfaceList

typedef NormalHypersurfaces regina::NNormalHypersurfaceList

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NNormalHypersurfaceList has now been renamed to NormalHypersurfaces.

## NNormalHypersurfaceVector

typedef NormalHypersurfaceVector regina::NNormalHypersurfaceVector

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NNormalHypersurfaceVector has now been renamed to NormalHypersurfaceVector.

## NNormalHypersurfaceVectorStandard

typedef HSVectorStandard regina::NNormalHypersurfaceVectorStandard

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NNormalHypersurfaceVectorStandard has now been renamed to HSVectorStandard.

## 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 are typically combined in a bitwise fashion using the HyperAlg type, and then passed to enumeration routines such as NormalHypersurfaces::enumerate().

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

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 displaying normal hypersurface 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.
HS_PRISM | Represents prism coordinates for normal hypersurfaces. For now, this coordinate system is for representation only; hypersurface vectors and lists cannot be created in this coordinate system. This will likely change in a future release of Regina, when prism coordinates will be supported for creation as well as viewing.
HS_EDGE_WEIGHT | Represents edge weight coordinates for normal hypersurfaces. This coordinate system is for representation only; hypersurface vectors and lists cannot be created in this coordinate system.

## 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.

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

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

## forCoords() [1/2]

template<typename FunctionObject , typename... Args>

ReturnsTraits<FunctionObject>::ReturnType regina::forCoords | ( | HyperCoords | coords,
|  | FunctionObject && | func,
|  | typename ReturnsTraits< FunctionObject >::ReturnType | defaultReturn,
|  | Args &&... | args
| ) |  |

Allows the user to call a template function whose template parameter matches a given value of HyperCoords, 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 hypersurfaces. All other coordinate systems are considered invalid for our purposes here.

In detail: the function object func must define a templated bracket operator, so that `func.operator()<HyperInfo<c>>(...)` is defined for any valid HyperCoords enum value c. Then, when the user calls `forCoords(coords, func, defaultReturn, ...)`, this routine will call `func.operator()<HyperInfo<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 variant of forCoords() that works with void functions, and so does not take the extra defaultReturn argument.

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

Python:
  Not present.

Parameters

  coords | the given normal hypersurface coordinate system.
  func | the function object whose bracket operator we will call with a HyperInfo<coords> object.
  defaultReturn | the value to return if the given coordinate system is invalid.
  args | any additional arguments to pass to the bracket operator for func. These will be copied/moved, so if you wish to pass references then you may need to wrap them in std::ref or std::cref.

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

## forCoords() [2/2]

template<typename FunctionObject , typename... Args>

ReturnsTraits<FunctionObject>::Void regina::forCoords | ( | HyperCoords | coords,
|  | FunctionObject && | func,
|  | Args &&... | args
| ) |  |

Allows the user to call a template function whose template parameter matches a given value of HyperCoords, 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 hypersurfaces. All other coordinate systems are considered invalid for our purposes here.

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

There is also a variant of forCoords() that works with functions with return values, and which takes an extra defaultReturn argument.

Precondition
  There must not exist a type FunctionObject::ReturnType. (or, if FunctionObject is a reference to a class/struct F, there must likewise not exist a type F::ReturnType). The existence of a type FunctionObject::ReturnType will cause the non-void variant of forCoords() to be used instead.

Python:
  Not present.

Parameters

  coords | the given normal hypersurface coordinate system.
  func | the function object whose bracket operator we will call with a HyperInfo<coords> object.
  args | any additional arguments to pass to the bracket operator for func. These will be copied/moved, so if you wish to pass references then you may need to wrap them in std::ref or std::cref.

Returns
  nothing; the return type `ReturnsTraits<FunctionObject>::Void` simply evaluates to `void`.

## makeEmbeddedConstraints()

EnumConstraints* regina::makeEmbeddedConstraints | ( | const Triangulation< 4 > * | triangulation,
|  | HyperCoords | coords
| ) |  |

Creates a new set of validity constraints representing the condition that normal hypersurfaces 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; this must be one of the predefined coordinate system constants in NormalHypersurfaces.

Returns
  a newly allocated set of constraints.

## makeMatchingEquations()

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

Creates a new set of normal hypersurface 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; this must be one of the predefined coordinate system constants in NormalHypersurfaces.

Returns
  a newly allocated set of matching equations.

## makeZeroVector()

NormalHypersurfaceVector* regina::makeZeroVector | ( | const Triangulation< 4 > * | triangulation,
|  | HyperCoords | coords
| ) |  |

Returns a new normal hypersurface 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 NormalHypersurfaceVector 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; this must be one of the predefined coordinate system constants in NormalHypersurfaces.

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

## operator|() [1/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.

## operator|() [2/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.

Copyright © 1999-2016, 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@maths.uq.edu.au).