Regina – Keeping your code updated

This page relates only to C++ and Python programmers.

Over time, Regina makes changes and improvements to its C++ and Python interfaces. This page explains how you will need to update your C++ code and/or Python scripts to work with the latest version of Regina.

Where possible, the old classes and routines that you should no longer use have been kept but marked as deprecated. These old deprecated classes and routines will be kept until the next major version (Regina 8.0), so that there is a comfortable transition period where your old code will still work. All of this deprecated code will be removed in Regina 8.0, whenever that may be.

This page only describes changes since Regina 7.0. If you have older code (from 2021 or earlier), you should also read the separate pages on:

moving from Regina 6.x to 7.x (December 2021) – this was an enormous update that made sweeping changes throughout the API;
moving from Regina 5.x to 6.x (January 2021);
moving from Regina 4.x to 5.x (September 2016).

Changes since Regina 7.0

Some general rules have been applied throughout the API:

All enumerations are now C++11 scoped enumerations with more natural names. For example, the old global constant NS_STANDARD is now NormalCoords::Standard, and the old class constant SnapPeaTriangulation::geometric_solution is now SnapPeaTriangulation::Solution::Geometric. All of the old names are now deprecated.
The corresponding “flags classes” (e.g., NormalAlgFlags) have also been renamed, but you should not need to refer to the new names explicitly. Just combine flags bitwise, such as (NormalAlg::TODO | NormalAlg::TODO), and let the compiler work out the type.
Elementary moves on triangulations (e.g., Pachner moves) and links (e.g., Reidemeister moves) have been overhauled. The old function form moveName(…, check, perform) is deprecated. To perform a move, you should now call moveName(…) without the check/perform arguments (the check is now mandatory). To do a read-only check on whether the move is allowed, use the new function form hasMoveName(…). There is also a new function form withMoveName(…), which returns a new optional triangulation or link instead of modifying the current one.
Several functions now verify some of their easy-to-test preconditions, and throw exceptions if these preconditions fail. Technically this is not a “real” API change, since users are expected to adhere to preconditions anyway; however, it is a practical change in behaviour. These changes are not individually outlined here on this page, but you can always consult the API documentation—every function that might throw an exception will declare this as part of its documentation.

In addition to the general changes outlined above, there are also specific changes to individual headers, classes, functions and/or constants. These are listed in the table below, along with suggestions for how you should change your code. Any changes in the behaviour of these routines or classes are noted in the comments column.

The blue cells indicate code that is still present in Regina, but is now deprecated (i.e., marked for removal in a future release). The red cells indicate code that has already been removed from Regina.

Deprecated code Replacement Comments

Classes, Enums and Type Aliases

Base64SigEncoding Base64SigEncoder and Base64SigDecoder The new classes carry state and have better error handling; however, this also means that this is not just a rename—if you were using Base64SigEncoding then you will need to read through how the interface has changed with the new classes.

DegreeLessThan, DegreeGreaterThan C++ lambda These classes were trivial, and nowadays a one-line lambda can do the same job.

Packet::ChangeEventSpan
PacketData<T>::ChangeEventSpan Packet::PacketChangeSpan
PacketData<T>::PacketChangeSpan

Triangle<3>::Type TriangleType This is now a global type, since it is now used with triangulations of all dimensions. The enumeration values have also been renamed—see the discussion above regarding general changes to enumerations.

Vertex<3>::LinkType Vertex<3>::Link The enumeration values have also been renamed—see the discussion above regarding general changes to enumerations.

Class Constructors

Laurent<T>(int exponent)
Laurent2<T>(int xExp, int yExp) Laurent<T>::initExp(int exponent)
Laurent2<T>::initExp(int xExp, int yExp) This is deprecated because it was not clear to the casual reader whether (for example) Laurent<T>(k) creates the term x^k or the constant k.

Polynomial<T>(int degree) Polynomial<T>::initExp(int degree) This is deprecated because it was not clear to the casual reader whether Polynomial(k) creates the term x^k or the constant k.

Triangulation<3>(const Link&) Link::complement()

Member Routines

BoolSet::empty()
Removed in Regina 7.4 BoolSet::clear() This rename was to avoid confusion with the more common pattern where empty() is a read-only query, not a destructive action.

Example<3>::cuspedGenusTwoTorus() Example<3>::idealGenusTwoHandlebody()

Example<3>::whiteheadLink() Example<3>::whitehead()

FacetPairing<dim>::toTextRep() FacetPairing<dim>::textRep()

FacetPairing<3>::followChain(size_t&, ...) FacetPairing<3>::followChain(ssize_t&, ...)

GroupPresentation::intelligentSimplify() GroupPresentation::simplify()

GroupPresentation::simplifyWord()
Removed in Regina 7.3 GroupPresentation::simplifyAndConjugate() This routine was renamed to make it clear that it might conjugate the given word. The behaviour has not changed (i.e., conjugation was always a possibility, even before the renaming).

HomGroupPresentation::intelligentNielsen()
HomGroupPresentation::intelligentSimplify() HomGroupPresentation::nielsen()
HomGroupPresentation::simplify()

Isomorphism<dim>::apply()
Isomorphism<dim>::applyInPlace() iso(tri)
tri = iso(tri)

Laurent<T>::init(int exponent)
Laurent2<T>::init(int xExp, int yExp) Laurent<T>::initExp(int exponent)
Laurent2<T>::initExp(int xExp, int yExp) This rename is to make it clear that (for example) Laurent<T>::init(k) initialises to x^k and not the just constant k.

Link::bracket(Algorithm, ProgressTracker*) Link::bracket(Algorithm, int, ProgressTracker*) The new integer argument specifies the number of threads to use, and defaults to 1.

Link::dumpConstruction() Link::source() The new function also takes an optional programming language argument.

Link::fromKnotSig() Link::fromSig() The old name is not deprecated, but the new name is preferred since signatures now support multiple-component links also.

Link::intelligentSimplify() Link::simplify()

Link::jones(Algorithm, ProgressTracker*) Link::jones(Algorithm, int, ProgressTracker*) The new integer argument specifies the number of threads to use, and defaults to 1.

Link::knotSig() Link::sig() The old name is not deprecated, but the new name is preferred since signatures now support multiple-component links also.

Matrix<T>::initialise() Matrix<T>::fill() The rename clarifies that this routine has nothing to do with initialised vs uninitialised matrices.

ModelLinkGraph::isValid()
Removed in Regina 7.4 — All graphs where isValid() used to return false are now fully supported as of Regina 7.4. There is no such thing as an invalid graph any more.

NormalHypersurface::doubleHypersurface() surface * 2 or surface *= 2

NormalSurface::doubleSurface() surface * 2 or surface *= 2

Packet::insertChildFirst()
Packet::insertChildLast()
Packet::insertChildAfter() Packet::prepend()
Packet::append()
Packet::insert()

Perm<n>::cachedComp() with two arguments Perm<n>::cachedConjugate(), or two uses of the one-argument Perm<n>::cachedComp() The two-argument cachedComp() (i.e., a three-way product) was only ever used internally for conjugation, and there is now a new cachedConjugate() routine for this instead.

Polynomial<T>::init(int degree) Polynomial<T>::initExp(int degree) This rename is to make it clear that init(k) initialises to x^k and not the just constant k.

TreeBag::subtype() TreeBag::niceIndex()

TreeBag::type() TreeBag::niceType() This function also now returns a NiceType enumeration value, not an int.

Triangle<3>::type()
Triangle<3>::subtype()
Triangle<3>::isMobiusBand()
Triangle<3>::isCone() Triangle<3>::triangleType()
Triangle<3>::triangleSubtype()
Triangle<3>::formsMobiusBand()
Triangle<3>::formsCone() These routines are also now available for (2-D) triangles within triangulations of any dimension ≥ 3.

Triangulation<dim>::barycentricSubdivision() Triangulation<3>::subdivide()

Triangulation<dim>::dumpConstruction() Triangulation<dim>::source() The new function also takes an optional programming language argument.

Triangulation<dim>::finiteToIdeal() Triangulation<dim>::makeIdeal() The old name is not deprecated, but the new name is preferred since it matches the terminology used in the graphical user interface.

Triangulation<3>::fourFourMove()
Triangulation<4>::fourFourMove() Triangulation<3>::move44()
Triangulation<4>::move44() See also the general discussion above regarding the overhaul of how elementary moves work in Regina.

Triangulation<3>::idealToFinite()
Triangulation<4>::idealToFinite() Triangulation<3>::truncateIdeal()
Triangulation<4>::truncateIdeal() The old name is not deprecated, but the new name is preferred since it matches the terminology used in the graphical user interface.

Triangulation<3>::intelligentSimplify()
Triangulation<4>::intelligentSimplify() Triangulation<3>::simplify()
Triangulation<4>::simplify()

Triangulation<3>::isHandlebody()
Removed in Regina 7.2 Triangulation<3>::recogniseHandlebody() This returns an integer genus, not a boolean, and so the name has been changed to avoid any misinterpretation.

Triangulation<dim>::makeDoubleCover() Triangulation<dim>::doubleCover() The new function also returns the double cover as a new triangulation, instead of modifying the current triangulation.

Triangulation<3>::minimizeBoundary()
Triangulation<3>::minimizeVertices() Triangulation<3>::minimiseBoundary()
Triangulation<3>::minimiseVertices() Regina uses British English consistently throughout its API.

Triangulation<3>::puncture(Tetrahedron<3>*) Triangulation<3>::puncture(Triangle<3>*) The location argument (i.e., the triangle) is also now optional.

Triangulation<3>::reorderTetrahedraBFS() Triangulation<3>::reorderBFS() This function is also now available in all dimensions.

Triangulation<dim>::simplifiedFundamentalGroup() Triangulation<dim>::setGroupPresentation()

Triangulation<3>::twoOneMove() Triangulation<3>::move21() See also the general discussion above regarding the overhaul of how elementary moves work in Regina.

Triangulation<dim>::twoZeroMove() Triangulation<dim>::move20() These moves are also now available in all dimensions, not just dimensions 3 and 4. See also the general discussion above regarding the overhaul of how elementary moves work in Regina.

Triangulation<3>::zeroTwoMove() Triangulation<3>::move02() See also the general discussion above regarding the overhaul of how elementary moves work in Regina.

Global Routines

regina::gcd()
regina::lcm() std::gcd()
std::lcm() GCD and LCM are now offered as part of the C++17 standard.

regina::simpler() regina::simplerThreeWay() These functions compare 2×2 matrices, or pairs of matrices. This change is like replacing a strict less-than operator a < b with a spaceship operator a <=> b.

Class Constants

Perm<n>::nPerms_1 Perm<n-1>::nPerms This deprecates old class constants such as Perm<4>::nPerms_1.

Perm<n>::Sk[i], where k < n
Perm<n>::orderedSk[i], where k < n Perm<n>::extend(Perm<k>::Sn[i])
Perm<n>::extend(Perm<k>::orderedSn[i]) This deprecates old class constants such as Perm<7>::S5 or Perm<4>::orderedS3.

Perm<n>::Sn_1[i] Perm<n>::extend(Perm<n-1>::Sn[i]) This deprecates old class constants such as Perm<4>::Sn_1.

Macros

ENABLE_MEMBER_FOR_REGINA_INTEGER static_assert(…) The suggested alternative (which is what Regina does now) is to use a static_assert to ensure that the member function in question is only instantiated for appropriate types. See Matrix<T> for some examples.

Deprecated code	Replacement	Comments
Classes, Enums and Type Aliases
`Base64SigEncoding`	`Base64SigEncoder` and `Base64SigDecoder`	The new classes carry state and have better error handling; however, this also means that this is not just a rename—if you were using `Base64SigEncoding` then you will need to read through how the interface has changed with the new classes.
`DegreeLessThan, DegreeGreaterThan`	C++ lambda	These classes were trivial, and nowadays a one-line lambda can do the same job.
`Packet::ChangeEventSpan` `PacketData<T>::ChangeEventSpan`	`Packet::PacketChangeSpan` `PacketData<T>::PacketChangeSpan`
`Triangle<3>::Type`	`TriangleType`	This is now a global type, since it is now used with triangulations of all dimensions. The enumeration values have also been renamed—see the discussion above regarding general changes to enumerations.
`Vertex<3>::LinkType`	`Vertex<3>::Link`	The enumeration values have also been renamed—see the discussion above regarding general changes to enumerations.
Class Constructors
`Laurent<T>(int exponent)` `Laurent2<T>(int xExp, int yExp)`	`Laurent<T>::initExp(int exponent)` `Laurent2<T>::initExp(int xExp, int yExp)`	This is deprecated because it was not clear to the casual reader whether (for example) `Laurent<T>(k)` creates the term `x^k` or the constant `k`.
`Polynomial<T>(int degree)`	`Polynomial<T>::initExp(int degree)`	This is deprecated because it was not clear to the casual reader whether `Polynomial(k)` creates the term `x^k` or the constant `k`.
`Triangulation<3>(const Link&)`	`Link::complement()`
Member Routines
`BoolSet::empty()` Removed in Regina 7.4	`BoolSet::clear()`	This rename was to avoid confusion with the more common pattern where `empty()` is a read-only query, not a destructive action.
`Example<3>::cuspedGenusTwoTorus()`	`Example<3>::idealGenusTwoHandlebody()`
`Example<3>::whiteheadLink()`	`Example<3>::whitehead()`
`FacetPairing<dim>::toTextRep()`	`FacetPairing<dim>::textRep()`
`FacetPairing<3>::followChain(size_t&, ...)`	`FacetPairing<3>::followChain(ssize_t&, ...)`
`GroupPresentation::intelligentSimplify()`	`GroupPresentation::simplify()`
`GroupPresentation::simplifyWord()` Removed in Regina 7.3	`GroupPresentation::simplifyAndConjugate()`	This routine was renamed to make it clear that it might conjugate the given word. The behaviour has not changed (i.e., conjugation was always a possibility, even before the renaming).
`HomGroupPresentation::intelligentNielsen()` `HomGroupPresentation::intelligentSimplify()`	`HomGroupPresentation::nielsen()` `HomGroupPresentation::simplify()`
`Isomorphism<dim>::apply()` `Isomorphism<dim>::applyInPlace()`	`iso(tri)` `tri = iso(tri)`
`Laurent<T>::init(int exponent)` `Laurent2<T>::init(int xExp, int yExp)`	`Laurent<T>::initExp(int exponent)` `Laurent2<T>::initExp(int xExp, int yExp)`	This rename is to make it clear that (for example) `Laurent<T>::init(k)` initialises to `x^k` and not the just constant `k`.
`Link::bracket(Algorithm, ProgressTracker*)`	`Link::bracket(Algorithm, int, ProgressTracker*)`	The new integer argument specifies the number of threads to use, and defaults to 1.
`Link::dumpConstruction()`	`Link::source()`	The new function also takes an optional programming language argument.
`Link::fromKnotSig()`	`Link::fromSig()`	The old name is not deprecated, but the new name is preferred since signatures now support multiple-component links also.
`Link::intelligentSimplify()`	`Link::simplify()`
`Link::jones(Algorithm, ProgressTracker*)`	`Link::jones(Algorithm, int, ProgressTracker*)`	The new integer argument specifies the number of threads to use, and defaults to 1.
`Link::knotSig()`	`Link::sig()`	The old name is not deprecated, but the new name is preferred since signatures now support multiple-component links also.
`Matrix<T>::initialise()`	`Matrix<T>::fill()`	The rename clarifies that this routine has nothing to do with initialised vs uninitialised matrices.
`ModelLinkGraph::isValid()` Removed in Regina 7.4	—	All graphs where `isValid()` used to return `false` are now fully supported as of Regina 7.4. There is no such thing as an invalid graph any more.
`NormalHypersurface::doubleHypersurface()`	`surface * 2` or `surface *= 2`
`NormalSurface::doubleSurface()`	`surface * 2` or `surface *= 2`
`Packet::insertChildFirst()` `Packet::insertChildLast()` `Packet::insertChildAfter()`	`Packet::prepend()` `Packet::append()` `Packet::insert()`
`Perm<n>::cachedComp() with two arguments`	`Perm<n>::cachedConjugate()`, or two uses of the one-argument `Perm<n>::cachedComp()`	The two-argument `cachedComp()` (i.e., a three-way product) was only ever used internally for conjugation, and there is now a new `cachedConjugate()` routine for this instead.
`Polynomial<T>::init(int degree)`	`Polynomial<T>::initExp(int degree)`	This rename is to make it clear that `init(k)` initialises to `x^k` and not the just constant `k`.
`TreeBag::subtype()`	`TreeBag::niceIndex()`
`TreeBag::type()`	`TreeBag::niceType()`	This function also now returns a `NiceType` enumeration value, not an `int`.
`Triangle<3>::type()` `Triangle<3>::subtype()` `Triangle<3>::isMobiusBand()` `Triangle<3>::isCone()`	`Triangle<3>::triangleType()` `Triangle<3>::triangleSubtype()` `Triangle<3>::formsMobiusBand()` `Triangle<3>::formsCone()`	These routines are also now available for (2-D) triangles within triangulations of any dimension ≥ 3.
`Triangulation<dim>::barycentricSubdivision()`	`Triangulation<3>::subdivide()`
`Triangulation<dim>::dumpConstruction()`	`Triangulation<dim>::source()`	The new function also takes an optional programming language argument.
`Triangulation<dim>::finiteToIdeal()`	`Triangulation<dim>::makeIdeal()`	The old name is not deprecated, but the new name is preferred since it matches the terminology used in the graphical user interface.
`Triangulation<3>::fourFourMove()` `Triangulation<4>::fourFourMove()`	`Triangulation<3>::move44()` `Triangulation<4>::move44()`	See also the general discussion above regarding the overhaul of how elementary moves work in Regina.
`Triangulation<3>::idealToFinite()` `Triangulation<4>::idealToFinite()`	`Triangulation<3>::truncateIdeal()` `Triangulation<4>::truncateIdeal()`	The old name is not deprecated, but the new name is preferred since it matches the terminology used in the graphical user interface.
`Triangulation<3>::intelligentSimplify()` `Triangulation<4>::intelligentSimplify()`	`Triangulation<3>::simplify()` `Triangulation<4>::simplify()`
`Triangulation<3>::isHandlebody()` Removed in Regina 7.2	`Triangulation<3>::recogniseHandlebody()`	This returns an integer genus, not a boolean, and so the name has been changed to avoid any misinterpretation.
`Triangulation<dim>::makeDoubleCover()`	`Triangulation<dim>::doubleCover()`	The new function also returns the double cover as a new triangulation, instead of modifying the current triangulation.
`Triangulation<3>::minimizeBoundary()` `Triangulation<3>::minimizeVertices()`	`Triangulation<3>::minimiseBoundary()` `Triangulation<3>::minimiseVertices()`	Regina uses British English consistently throughout its API.
`Triangulation<3>::puncture(Tetrahedron<3>*)`	`Triangulation<3>::puncture(Triangle<3>*)`	The location argument (i.e., the triangle) is also now optional.
`Triangulation<3>::reorderTetrahedraBFS()`	`Triangulation<3>::reorderBFS()`	This function is also now available in all dimensions.
`Triangulation<dim>::simplifiedFundamentalGroup()`	`Triangulation<dim>::setGroupPresentation()`
`Triangulation<3>::twoOneMove()`	`Triangulation<3>::move21()`	See also the general discussion above regarding the overhaul of how elementary moves work in Regina.
`Triangulation<dim>::twoZeroMove()`	`Triangulation<dim>::move20()`	These moves are also now available in all dimensions, not just dimensions 3 and 4. See also the general discussion above regarding the overhaul of how elementary moves work in Regina.
`Triangulation<3>::zeroTwoMove()`	`Triangulation<3>::move02()`	See also the general discussion above regarding the overhaul of how elementary moves work in Regina.
Global Routines
`regina::gcd()` `regina::lcm()`	`std::gcd()` `std::lcm()`	GCD and LCM are now offered as part of the C++17 standard.
`regina::simpler()`	`regina::simplerThreeWay()`	These functions compare 2×2 matrices, or pairs of matrices. This change is like replacing a strict less-than operator `a < b` with a spaceship operator `a <=> b`.
Class Constants
`Perm<n>::nPerms_1`	`Perm<n-1>::nPerms`	This deprecates old class constants such as `Perm<4>::nPerms_1`.
`Perm<n>::Sk[i]`, where k < n `Perm<n>::orderedSk[i]`, where k < n	`Perm<n>::extend(Perm<k>::Sn[i])` `Perm<n>::extend(Perm<k>::orderedSn[i])`	This deprecates old class constants such as `Perm<7>::S5` or `Perm<4>::orderedS3`.
`Perm<n>::Sn_1[i]`	`Perm<n>::extend(Perm<n-1>::Sn[i])`	This deprecates old class constants such as `Perm<4>::Sn_1`.
Macros
`ENABLE_MEMBER_FOR_REGINA_INTEGER`	`static_assert(…)`	The suggested alternative (which is what Regina does now) is to use a `static_assert` to ensure that the member function in question is only instantiated for appropriate types. See `Matrix<T>` for some examples.

Back to main page ...