Regina Calculation Engine
Namespaces | Classes | Macros | Typedefs | Enumerations | Enumerator | Functions | Variables
Engine Structure

Overall structure of the calculation engine. More...

Namespaces

 regina
 Contains the entire Regina calculation engine.
 

Classes

struct  regina::Output< T, supportsUtf8 >
 A common base class for objects that write human-readable text output. More...
 
struct  regina::ShortOutput< T, supportsUtf8 >
 A common base class for objects that provide short text output only. More...
 
struct  regina::OutputBase< T >
 Provides a typedef to help identify where in the class hierarchy the output functions T::str() and T::detail() are implemented. More...
 

Macros

#define REGINA_INLINE_REQUIRED   inline
 A synonym for inline, used in some special cases to avoid noisy warnings under Windows. More...
 
#define REGINA_API
 All non-templated, non-static functions, classes and global variables that are part of Regina's public interface must be declared with REGINA_API. More...
 
#define REGINA_LOCAL
 Classes and functions that are local to the current compilation unit and should not be publicly exported may be declared with REGINA_LOCAL. More...
 

Typedefs

typedef std::remove_reference< decltype(test(std::declval< T >)))>::type regina::OutputBase< T >::type
 The class in which T::str() and T::detail() are implemented. More...
 
typedef Algorithm regina::TuraevViroAlg
 Deprecated alias for Algorithm. More...
 

Enumerations

enum  regina::Algorithm { regina::ALG_DEFAULT = 0, regina::ALG_BACKTRACK = 1, regina::ALG_TREEWIDTH = 2, regina::ALG_NAIVE = 3 }
 Represents various classes of algorithms that Regina can use for computations. More...
 

Functions

const char * regina::versionString ()
 Returns the full version number of this calculation engine. More...
 
int regina::versionMajor ()
 Returns the major version number of this calculation engine. More...
 
int regina::versionMinor ()
 Returns the minor version number of this calculation engine. More...
 
bool regina::versionUsesUTF8 (const char *version)
 Did the given version of Regina consistently use UTF-8 in its data files? More...
 
const char * regina::versionSnapPy ()
 Returns the version of SnapPy whose underlying SnapPea kernel is built into Regina. More...
 
const char * regina::versionSnapPea ()
 An alias for versionSnapPy(), which returns the version of SnapPy whose underlying SnapPea kernel is built into Regina. More...
 
bool regina::hasInt128 ()
 Does this particular build of Regina support native 128-bit arithmetic? More...
 
int regina::politeThreads ()
 A suggestion for user interfaces as to how many threads should be used for parallel computations. More...
 
int regina::testEngine (int value)
 Tests to see if an interface can successfully communicate with the underlying C++ calculation engine. More...
 
std::string regina::Output< T, supportsUtf8 >::str () const
 Returns a short text representation of this object. More...
 
std::string regina::Output< T, supportsUtf8 >::utf8 () const
 Returns a short text representation of this object using unicode characters. More...
 
std::string regina::Output< T, supportsUtf8 >::detail () const
 Returns a detailed text representation of this object. More...
 
template<class T , bool supportsUtf8>
std::ostream & regina::operator<< (std::ostream &out, const Output< T, supportsUtf8 > &object)
 Writes the short text representation of the given object to the given output stream. More...
 
void regina::ShortOutput< T, supportsUtf8 >::writeTextLong (std::ostream &out) const
 A default implementation for detailed output. More...
 
constexpr bool regina::standardDim (int dim)
 Indicates whether the given dimension is one of Regina's standard dimensions. More...
 

Variables

constexpr Algorithm regina::TV_DEFAULT = ALG_DEFAULT
 Deprecated alias for ALG_DEFAULT. More...
 
constexpr Algorithm regina::TV_BACKTRACK = ALG_BACKTRACK
 Deprecated alias for ALG_BACKTRACK. More...
 
constexpr Algorithm regina::TV_TREEWIDTH = ALG_TREEWIDTH
 Deprecated alias for ALG_TREEWIDTH. More...
 
constexpr Algorithm regina::TV_NAIVE = ALG_NAIVE
 Deprecated alias for ALG_NAIVE. More...
 

Detailed Description

Overall structure of the calculation engine.

Macro Definition Documentation

◆ REGINA_API

#define REGINA_API

All non-templated, non-static functions, classes and global variables that are part of Regina's public interface must be declared with REGINA_API.

Template classes or functions should not be declared with REGINA_API, but any explicit instantiations should. Global variables must also be declared with extern, as per normal.

This is required for DLL linking under Windows, and also to avoid breakage with optimisations such as gcc's -fvisibility=hidden.

Note: When building the Regina calculation engine shared library, REGINA_DLL_EXPORTS must be defined (this ensures that API symbols are marked for export). When importing (using) this library, REGINA_DLL_EXPORTS must not be defined (this ensures that API symbols are marked for import instead).

◆ REGINA_INLINE_REQUIRED

#define REGINA_INLINE_REQUIRED   inline

A synonym for inline, used in some special cases to avoid noisy warnings under Windows.

Typically this macro is used with inline functions of some class or struct that are called by other inline function(s).

Such a function should:

  • be declared as REGINA_INLINE_REQUIRED at the point where the function is first declared inside the class definition;
  • be declared again as inline when the function is later defined (as Regina does with all its inline functions).

The reason for using REGINA_INLINE_REQUIRED in such situations is to avoid noisy warnings about dllimport attributes under Windows. The reason for using this particular macro instead of just the keyword inline is to remind the Regina developers not to remove it.

This is not the first, and will surely not be the last, piece of code bloat that Windows forces upon us. Sigh.

◆ REGINA_LOCAL

#define REGINA_LOCAL

Classes and functions that are local to the current compilation unit and should not be publicly exported may be declared with REGINA_LOCAL.

Use of this macro is optional.

Typedef Documentation

◆ TuraevViroAlg

Deprecated alias for Algorithm.

Deprecated:
The TuraevViroAlg enumeration is deprecated, in favour of the more general Algorithm enumeration type. The old constants TV_DEFAULT, TV_BACKTRACK, TV_TREEWIDTH and TV_NAIVE correspond to the new constants ALG_DEFAULT, ALG_BACKTRACK, ALG_TREEWIDTH and ALG_NAIVE respectively.

◆ type

template<class T >
typedef std::remove_reference< decltype(test(std::declval<T>)))>::type regina::OutputBase< T >::type

The class in which T::str() and T::detail() are implemented.

If T is derived from the Output template class, then this type is the corresponding Output<X> base class. Otherwise, this type is T itself.

Note
The implementation of this typedef does not look for str() or detail() at all. Instead, it is based purely on the inheritance condition as stated above.

Enumeration Type Documentation

◆ Algorithm

Represents various classes of algorithms that Regina can use for computations.

A function that takes an Algorithm argument need not support all types of algorithm - if an unsupported algorithm is passed then Regina will fall back to ALG_DEFAULT.

This enumeration type does not allow constants to be combined using the OR operator.

For some computations where the user can exert more fine-grained control over the underlying algorithm, a more specialised enumeration type is used instead. For example, see NormalSurfaces::enumerate(), which uses the specialised algorithm types NormalAlg and NormalAlgFlags.

Enumerator
ALG_DEFAULT 

The default algorithm.

Here Regina will choose whichever algorithm it thinks (rightly or wrongly) is most appropriate.

ALG_BACKTRACK 

An optimised backtracking algorithm.

This typically works over some search tree (often of exponential size or worse), but include significant optimisations to prune the search tree and/or cache computations where possible.

ALG_TREEWIDTH 

A treewidth-based algorithm.

Typically this uses dynamic programming over a tree decomposition of some underlying graph. Such algorithms are often fast for triangulations or links with small treewidth, but may require large amounts of memory.

ALG_NAIVE 

A naive algorithm.

This typically works directly with the underlying definitions (e.g., computing Turaev-Viro as a state sum), without further optimisations.

Warning
Naive algorithms should only be used for comparison and experimentation. Due to their slow performance, they are not suitable for "real" applications.

Function Documentation

◆ detail()

template<class T , bool supportsUtf8 = false>
std::string regina::Output< T, supportsUtf8 >::detail ( ) const

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.

◆ hasInt128()

bool regina::hasInt128 ( )

Does this particular build of Regina support native 128-bit arithmetic?

On those platforms that do support native 128-bit arithmetic, some expensive algorithms (in particular for normal surface enumeration) are optimised to run significantly faster in some cases.

Returns
true if and only if this build supports native 128-bit arithmetic.

◆ operator<<()

template<class T , bool supportsUtf8>
std::ostream& regina::operator<< ( std::ostream &  out,
const Output< T, supportsUtf8 > &  object 
)

Writes the short text representation of the given object to the given output stream.

This is equivalent to calling out << object.str().

Parameters
outthe output stream to which to write.
objectthe object to write.
Returns
a reference to the given output stream.

◆ politeThreads()

int regina::politeThreads ( )

A suggestion for user interfaces as to how many threads should be used for parallel computations.

The current implementation returns approximately half the number of cores available on the machine.

Returns
the suggested number of threads to use.

◆ standardDim()

constexpr bool regina::standardDim ( int  dim)
constexpr

Indicates whether the given dimension is one of Regina's standard dimensions.

Standard dimensions offer significantly richer functionality for triangulations than generic dimensions.

Parameters
dimthe dimension in question.
Returns
true if and only if dim is one of Regina's standard dimensions.

◆ str()

template<class T , bool supportsUtf8 = false>
std::string regina::Output< T, supportsUtf8 >::str ( ) const

Returns a short text representation of this object.

This text should be human-readable, should fit on a single line, and should not end with a newline. Where possible, it should use plain ASCII characters.

Python:\n In addition to str(), this is also used as the
Python "stringification" function str().
Returns
a short text representation of this object.

◆ testEngine()

int regina::testEngine ( int  value)

Tests to see if an interface can successfully communicate with the underlying C++ calculation engine.

This routine simply uses the engine to return the same value that is passed to it; it can be used to test whether communications between the interface and the C++ engine are working properly.

Parameters
valueany integer; this same integer will be returned.
Returns
the same integer that was passed as value.

◆ utf8()

template<class T , bool supportsUtf8 = false>
std::string regina::Output< T, supportsUtf8 >::utf8 ( ) const

Returns a short text representation of this object using unicode characters.

Like str(), this text should be human-readable, should fit on a single line, and should not end with a newline. In addition, it may use unicode characters to make the output more pleasant to read. This string will be encoded in UTF-8.

Returns
a short text representation of this object.

◆ versionMajor()

int regina::versionMajor ( )

Returns the major version number of this calculation engine.

For instance, version 2.3.1 would have major version 2.

Returns
the major version number of this calculation engine.

◆ versionMinor()

int regina::versionMinor ( )

Returns the minor version number of this calculation engine.

For instance, version 2.3.1 would have minor version 3.

Returns
the minor version number of this calculation engine.

◆ versionSnapPea()

const char* regina::versionSnapPea ( )

An alias for versionSnapPy(), which returns the version of SnapPy whose underlying SnapPea kernel is built into Regina.

See versionSnapPy() for details.

Returns
the version of SnapPy whose underlying SnapPea kernel is built into Regina.

◆ versionSnapPy()

const char* regina::versionSnapPy ( )

Returns the version of SnapPy whose underlying SnapPea kernel is built into Regina.

The SnapPea kernel is now maintained by the larger SnapPy project, and Regina sources its version of the SnapPea kernel from one of the recent SnapPy releases. See http://snappy.computop.org/ for details.

In Regina, you can access the SnapPea kernel through the SnapPeaTriangulation class.

Returns
the version of SnapPy whose underlying SnapPea kernel is built into Regina.

◆ versionString()

const char* regina::versionString ( )

Returns the full version number of this calculation engine.

For instance, version 2.3.1 would have full version "2.3.1".

Returns
the version of this calculation engine.

◆ versionUsesUTF8()

bool regina::versionUsesUTF8 ( const char *  version)

Did the given version of Regina consistently use UTF-8 in its data files?

In Regina versions 4.4 and below, no particular attention was paid to character encodings. As a result, the GUI typically stored data in LATIN1 (the default for the Qt libraries).

As of Regina 4.5, all strings are now stored in UTF-8 where possible.

This routine allows programs to determine which regime a particular version of Regina belongs to. This can be useful when working with Regina data files on a low-level basis.

Any whitespace in the version string will confuse the result, and the return value will be undefined.

As a special case, an empty string is treated as belonging to the UTF-8 regime.

Parameters
versiona version string from some release of Regina, such as "4.2". This must not contain any whitespace padding.
Returns
true if the given version uses UTF-8 consistently, or false if the given version is an older version that did not pay attention to character encodings.

◆ writeTextLong()

template<class T , bool supportsUtf8>
void regina::ShortOutput< T, supportsUtf8 >::writeTextLong ( std::ostream &  out) const
inline

A default implementation for detailed output.

This routine simply calls T::writeTextShort() and appends a final newline.

Python:\n Not present.
Parameters
outthe output stream to which to write.

Variable Documentation

◆ TV_BACKTRACK

constexpr Algorithm regina::TV_BACKTRACK = ALG_BACKTRACK
constexpr

Deprecated alias for ALG_BACKTRACK.

Deprecated:
The old constant TV_BACKTRACK has been replaced by the constant ALG_BACKTRACK, and the underlying enumeration type has been renamed from TuraevViroAlg to Algorithm.

◆ TV_DEFAULT

constexpr Algorithm regina::TV_DEFAULT = ALG_DEFAULT
constexpr

Deprecated alias for ALG_DEFAULT.

Deprecated:
The old constant TV_DEFAULT has been replaced by the constant ALG_DEFAULT, and the underlying enumeration type has been renamed from TuraevViroAlg to Algorithm.

◆ TV_NAIVE

constexpr Algorithm regina::TV_NAIVE = ALG_NAIVE
constexpr

Deprecated alias for ALG_NAIVE.

Deprecated:
The old constant TV_NAIVE has been replaced by the constant ALG_NAIVE, and the underlying enumeration type has been renamed from TuraevViroAlg to Algorithm.

◆ TV_TREEWIDTH

constexpr Algorithm regina::TV_TREEWIDTH = ALG_TREEWIDTH
constexpr

Deprecated alias for ALG_TREEWIDTH.

Deprecated:
The old constant TV_TREEWIDTH has been replaced by the constant ALG_TREEWIDTH, and the underlying enumeration type has been renamed from TuraevViroAlg to Algorithm.

Copyright © 1999-2020, 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).