Regina Calculation Engine
|
Regina's calculation engine is provided as a shared C++ library, and this API documentation describes the native C++ interface for working with this library.
Regina also provides a Python module, which wraps many of the classes, functions, methods and so on from this library so that Python users can access them.
Python users should read this documentation as follows:
std::string
becomes the native Python string type.It is important to understand how Python's equality tests x == y
and x is y
operate under Python.
If x is a Python variable representing one of Regina's objects, then internally x stores a reference to one of Regina's native C++ objects. Importantly, there may be many different Python variables that all stores references to the same underlying C++ object.
This means that the Python test x is y
is unreliable. If x is y
returns True
then certainly x and y refer to the same C++ object; however, if x is y
returns False
then it is still possible that they refer to the same C++ object.
The solution is to always use the test x == y
. Regina offers three types of classes, and these behave differently under Python:
Some classes use comparison by value. Here x == y
tests whether the contents of x and y are mathematically equivalent. Examples of such classes are Integer, Rational, and AbelianGroup.
These classes all provide C++ comparison operators == and !=. You can read the documentation for these operators to understand exactly what mathematical condition(s) are being tested.
Some classes use comparison by reference. Here x == y
tests whether x and y refer to the same underlying C++ object. This is similar to how the test x is y
would behave in a native Python application. Examples of such classes are Triangulation<3> and Tetrahedron<3>.
These classes do not provide C++ comparison operators == or !=.
If you wish to find out how a particular class C behaves, you can examine the attribute C.equalityType
. This will return one of the values BY_VALUE
, BY_REFERENCE
or NEVER_INSTANTIATED
respectively: