Engine Structure

Overall structure of the calculation engine. More...

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 type alias to help identify where in the class hierarchy the output functions T::str() and T::detail() are implemented. 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...
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...
constexpr bool	regina::standardDim (int dim)
	Indicates whether the given dimension is one of Regina's standard dimensions. More...

Detailed Description

Overall structure of the calculation engine.

Enumeration Type Documentation

Algorithm

enum regina::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 the NormalSurfaces class constructor, 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

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

out	the output stream to which to write.
object	the 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

dim	the dimension in question.

Returns

true if and only if dim is one of Regina's standard dimensions.

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

value

any integer; this same integer will be returned.

Returns

the same integer that was passed as value.

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 at the time 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

version

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