Regina Calculation Engine
Public Member Functions | List of all members
regina::Tangle Class Reference

Represents a 2-tangle in the 3-ball. More...

#include <link/tangle.h>

Inheritance diagram for regina::Tangle:
regina::Output< Tangle >

Public Member Functions

Tangleoperator= (const Tangle &)=delete
 
std::string str () const
 
Returns a short text representation of this object. More...
 
std::string utf8 () const
 Returns a short text representation of this object using unicode characters. More...
 
std::string detail () const
 Returns a detailed text representation of this object. More...
 
Constructors and Destructors
 Tangle ()
 Constructs the zero tangle. More...
 
 Tangle (int twists)
 Constructs a tangle from the given number of twists. More...
 
 Tangle (int num, int den)
 Constructs a rational tangle with the given parameters. More...
 
 Tangle (const Link &knot)
 Creates a tangle from two parallel copies of the given knot. More...
 
 Tangle (const Tangle &copy)
 Constructs a new copy of the given tangle. More...
 
 ~Tangle ()
 Destroys this tangle. More...
 
Crossings and Strings
char type () const
 Returns the type of this tangle. More...
 
size_t size () const
 Returns the number of crossings in this tangle. More...
 
Crossingcrossing (size_t index) const
 Returns a pointer to the crossing at the given index within this tangle. More...
 
StrandRef begin (int string) const
 Returns the crossing closest to the beginning of the given string. More...
 
StrandRef end (int string) const
 Returns the crossing closest to the end of the given string. More...
 
StrandRef translate (const StrandRef &other) const
 Translates a strand reference for some other tangle into the corresponding strand reference for this tangle. More...
 
Editing
void swapContents (Tangle &other)
 Swaps the contents of this and the given tangle. More...
 
void twist (int sign=1)
 Adds a twist to the right-hand end of this tangle. More...
 
void turn (int direction=1)
 Rotates this tangle by 90 degrees. More...
 
void changeAll ()
 Switches the upper and lower strands of every crossing in the tangle. More...
 
bool r1 (Crossing *crossing, bool check=true, bool perform=true)
 Tests for and/or performs a type I Reidemeister move to remove a crossing. More...
 
bool r2 (StrandRef arc, bool check=true, bool perform=true)
 Tests for and/or performs a type II Reidemeister move to remove two crossings. More...
 
bool r2 (Crossing *crossing, bool check=true, bool perform=true)
 Tests for and/or performs a type II Reidemeister move to remove two crossings. More...
 
bool simplifyToLocalMinimum (bool perform=true)
 Uses type I and II Reidemeister moves to reduce the tangle monotonically to some local minimum number of crossings. More...
 
Algebra on Tangles
void add (const Tangle &other)
 Adds the given tangle to the right-hand side of this tangle. More...
 
void negate ()
 Reflects this tangle through the diagonal axis running from the top-left to bottom-right corners of the diagram. More...
 
void box (const Tangle &topLeft, const Tangle &topRight, const Tangle &bottomLeft, const Tangle &bottomRight)
 Encloses this tangle with the four given tangles in a box configuration. More...
 
LinknumClosure () const
 Forms the numerator closure of this tangle. More...
 
LinkdenClosure () const
 Forms the denominator closure of this tangle. More...
 
Output
void writeTextShort (std::ostream &out) const
 
Writes a short text representation of this tangle to the given output stream. More...
 
void writeTextLong (std::ostream &out) const
 
Writes a detailed text representation of this tangle to the given output stream. More...
 
Exporting Tangles
std::string orientedGauss () const
 Outputs an oriented Gauss code for this tangle. More...
 
void orientedGauss (std::ostream &out) const
 
Writes an oriented Gauss code for this tangle to the given output stream. More...
 

Static Public Member Functions

Building Tangles
static TanglefromOrientedGauss (const std::string &str)
 Creates a new tangle from an oriented Gauss code. More...
 
template<typename Iterator >
static TanglefromOrientedGauss (Iterator begin, Iterator end)
 
Creates a new tangle from an oriented Gauss code. More...
 

Detailed Description

Represents a 2-tangle in the 3-ball.

Regina does not allow closed components in a tangle; in other words, a tangle in Regina is a proper embedding of exactly two arcs in the 3-ball with the corresponding four endpoints attached to four marked points on the 3-ball boundary.

Regina stores tangles as projections, with the four endpoints fixed at the top-left, top-right, bottom-left and bottom-right corners of the diagram.

Each tangles has a type, indicating how the four endpoints are connected. The three possible types are:

Internally, Regina numbers the two strings 0 and 1: string 0 will always be the one attached to the top-left endpoint. Regina also assigns each string an orientation: for a horizontal or diagonal tangle this will always be from left to right, and for a vertical tangle this will always be from top to bottom.

When traversing a tangle, if you reach one of the endpoints of a string then the corresponding return value of Crossing::next() or Crossing::prev() (whichever is relevant) will be a null strand reference.

Constructor & Destructor Documentation

◆ Tangle() [1/5]

regina::Tangle::Tangle ( )
inline

Constructs the zero tangle.

This is the horizontal tangle with no crossings.

◆ Tangle() [2/5]

regina::Tangle::Tangle ( int  twists)

Constructs a tangle from the given number of twists.

If twists is positive, then the new tangle will consist of twists positive twists, stacked from left to right. If twists is negative, then the new tangle will consist of -(twists) negative twists, likewise stacked from left to right. If twists is zero, then the new tangle will be a horizontal tangle with no crossings at all.

In all cases, this is equivalent to calling the rational tangle constructor Tangle(twists, 1).

Parameters
twiststhe number of twists to perform; this may be positive, negative or zero.

◆ Tangle() [3/5]

regina::Tangle::Tangle ( int  num,
int  den 
)

Constructs a rational tangle with the given parameters.

Here we use the following convention (following the description that Adams gives in The Knot Book):

  • the zero tangle is horizontal with no crossings;
  • the infinity tangle is vertical with no crossings;
  • the +1 tangle is diagonal with one crossing, where the upper string runs from bottom-left to top-right.
Precondition
The given arguments are coprime.
Parameters
numthe numerator of the rational number that describes this tangle.
denthe denominator of the rational number that describes this tangle; this may be 0 (representing the infinity tangle).

◆ Tangle() [4/5]

regina::Tangle::Tangle ( const Link knot)

Creates a tangle from two parallel copies of the given knot.

Specifically, the tangle will consist of two parallel copies of the given knot diagram, which will be broken just before the starting strand as returned by knot.component(0).

The two resulting endpoints that appear just before the starting strand will form the top-left and bottom-left endpoints of this tangle, and the endpoints on the other side of the break (which will be just after the parallel copies of the final strand knot.component(0).prev()) will form the top-right and bottom-right endpoints of this tangle.

The tangle will contain 4 * knot.size() crossings in total.

Precondition
The argument contains exactly one component (i.e., it is actually a knot, and not empty or a multiple-component link).
Parameters
knotthe knot to break and duplicate to form this tangle.

◆ Tangle() [5/5]

regina::Tangle::Tangle ( const Tangle copy)

Constructs a new copy of the given tangle.

Parameters
copythe tangle to copy.

◆ ~Tangle()

regina::Tangle::~Tangle ( )
inline

Destroys this tangle.

The Crossing objects contained in this tangle will also be destroyed.

Member Function Documentation

◆ add()

void regina::Tangle::add ( const Tangle other)

Adds the given tangle to the right-hand side of this tangle.

In Conway's notation, if this tangle is t, then this routine converts this into (t + other).

Specifically: this routine will attach the two right-hand endpoints of this tangle to the two left-hand endpoints of a copy of other.

This tangle will be changed directly. The tangle other (passed as the argumet) will be left unchanged.

It is allowed to pass this tangle as other.

Precondition
It is not the case that both this and other are vertical tangles (which would cause the addition to create a closed link component).
Parameters
otherthe tangle to add to this.

◆ begin()

StrandRef regina::Tangle::begin ( int  string) const
inline

Returns the crossing closest to the beginning of the given string.

Recall from the class notes that string 0 is always attached to the top-left endpoint. Recall also that strings are oriented from left-to-right for a horizontal or diagonal tangle, and from top-to-bottom for a vertical tangle.

Parameters
stringindicates which of the two strings in this tangle to query; this must be either 0 or 1.
Returns
the crossing closest to the beginning of the given string, or a null reference if the given string contains no crossings.

◆ box()

void regina::Tangle::box ( const Tangle topLeft,
const Tangle topRight,
const Tangle bottomLeft,
const Tangle bottomRight 
)

Encloses this tangle with the four given tangles in a box configuration.

The five tangles will be connected as shown, with this tangle in the centre:

 \     /
  O---O
 / \ / \
 |  O  |
 \ / \ /
  O---O
 /     \

The top-left corner of the argument topLeft will become the top-left corner of the resulting tangle, and so on for the other three corners.

This tangle will be changed directly. The other four other tangles (passed as arguments) will be left unchanged.

You may use the same tangle for multiple arguments, and you may even use this tangle for one or more arguments.

Precondition
Every string in all five tangles (the four arguments and this) has at least one crossing.
None of the five tangles (the four arguments and this) have types that would result in a closed link component after this operation is performed.
Parameters
topLeftthe tangle to connect to the top-left corner of this.
topRightthe tangle to connect to the top-right corner of this.
bottomLeftthe tangle to connect to the bottom-left corner of this.
bottomRightthe tangle to connect to the bottom-right corner of this.

◆ changeAll()

void regina::Tangle::changeAll ( )

Switches the upper and lower strands of every crossing in the tangle.

This operation corresponds to reflecting the tangle through the plane on which the diagram is drawn.

◆ crossing()

Crossing * regina::Tangle::crossing ( size_t  index) const
inline

Returns a pointer to the crossing at the given index within this tangle.

For a tangle with n crossings, the crossings are numbered from 0 to n-1 inclusive.

Warning
If some crossings are added or removed then the indices of other crossings might change. If you wish to track a particular crossing through such operations then you should use the pointer to the relevant Crossing object instead.
Parameters
indexthe index of the requested crossing. This must be between 0 and size()-1 inclusive.
Returns
the crossing at the given index.

◆ denClosure()

Link* regina::Tangle::denClosure ( ) const

Forms the denominator closure of this tangle.

This is the link created by joining the two left endpoints of this tangle, and also joining the two right endpoints.

Returns
a newly created link that is the denominator closure of this tangle.

◆ detail()

std::string regina::Output< Tangle , false >::detail ( ) const
inherited

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.

◆ end()

StrandRef regina::Tangle::end ( int  string) const
inline

Returns the crossing closest to the end of the given string.

Recall from the class notes that string 0 is always attached to the top-left endpoint. Recall also that strings are oriented from left-to-right for a horizontal or diagonal tangle, and from top-to-bottom for a vertical tangle.

Parameters
stringindicates which of the two strings in this tangle to query; this must be either 0 or 1.
Returns
the crossing closest to the end of the given string, or a null reference if the given string contains no crossings.

◆ fromOrientedGauss() [1/2]

static Tangle* regina::Tangle::fromOrientedGauss ( const std::string &  str)
static

Creates a new tangle from an oriented Gauss code.

Oriented Gauss codes for tangles are an extension of oriented Gauss codes for knots. Whilst oriented Gauss codes for knots are used elsewhere (they are based on a format used by Andreeva et al.), these codes for tangles are specific to Regina (so you should not expect other software to understand them).

The format works as follows:

  • Label the crossings arbitrarily as 1, 2, ..., n.
  • Write one of the tokens -, | or x to represent a horizontal, vertical or diagonal tangle respectively.
  • Start at the top-left endpoint and follow this string to its other endpoint. At every crossing that you pass, write a token of the form +<k, -<k, +>k or ->k, where:
    • the symbol + indicates that you are passing over the crossing labelled k, and the symbol - indicates that you are passing under the crossing labelled k;
    • the symbol < indicates that the other strand of the crossing passes from right to left, and > indicates that the other strand passes from left to right.
  • Write the token _ to indicate that the first string has finished.
  • Start at the beginning of the other string (for horizontal or diagonal tangles, this is the bottom-left endpoint, and for vertical tangles this is the top-right endpoint). As before, follow this string to its other endpoint, writing a token of the form +<k, -<k, +>k or ->k at every crossing that you pass.

Be aware that, once the tangle has been constructed, the crossings 1, ..., n will have been reindexed as 0, ..., n-1 (since every Tangle object numbers its crossings starting from 0).

As an example, you can construct the rational tangle -3/4 using the following code:

| -<1 +>2 -<3 +>4 _ -<5 -<4 +>3 -<2 +>1 +>5

There are two variants of this routine. This variant takes a single string, where the tokens have been combined together and separated by whitespace. The other variant takes a sequence of tokens, defined by a pair of iterators.

In this variant (the string variant), the given string may contain additional leading or trailing whitespace.

Warning
While this routine does some error checking on the input, it does not test for the viability of the diagram (i.e., whether the given crossings with the given signs actually produce a tangle of the given type with the correct endpoints). Of course non-viable inputs are not allowed, and it is currently up to the user to enforce this.
Parameters
stran oriented Gauss code for a tangle, as described above.
Returns
a newly constructed tangle, or null if the input was found to be invalid.

◆ fromOrientedGauss() [2/2]

template<typename Iterator >
static Tangle* regina::Tangle::fromOrientedGauss ( Iterator  begin,
Iterator  end 
)
static


Creates a new tangle from an oriented Gauss code.

Oriented Gauss codes for tangles are an extension of oriented Gauss codes for knots. Whilst oriented Gauss codes for knots are used elsewhere (they are based on a format used by Andreeva et al.), these codes for tangles are specific to Regina (so you should not expect other software to understand them).

See fromOrientedGauss(const std::string&) for a detailed description of this format as it is used in Regina.

There are two variants of this routine. The other variant (fromOrientedGauss(const std::string&), which offers more detailed documentation) takes a single string, where the tokens have been combined together and separated by whitespace. This variant takes a sequence of tokens, defined by a pair of iterators.

Precondition
Iterator is a random access iterator type.
Dereferencing such an iterator produces either a C-style string (which can be cast to const char*) or a C++-style string (which can be cast to const std::string&).
The tokens in the input sequence do not contain any whitespace.
Warning
While this routine does some error checking on the input, it does not test for the viability of the diagram (i.e., whether the given crossings with the given signs actually produce a tangle of the given type with the correct endpoints). Of course non-viable inputs are not allowed, and it is currently up to the user to enforce this.
Python
Instead of a pair of begin and past-the-end iterators, this routine takes a Python list of strings.
Parameters
beginan iterator that points to the beginning of the sequence of tokens for an oriented Gauss code.
endan iterator that points past the end of the sequence of tokens for an oriented Gauss code.
Returns
a newly constructed tangle, or null if the input was found to be invalid.

◆ negate()

void regina::Tangle::negate ( )

Reflects this tangle through the diagonal axis running from the top-left to bottom-right corners of the diagram.

In Conway's notation, this negates the tangle.

◆ numClosure()

Link* regina::Tangle::numClosure ( ) const

Forms the numerator closure of this tangle.

This is the link created by joining the two top endpoints of this tangle, and also joining the two bottom endpoints.

Returns
a newly created link that is the numerator closure of this tangle.

◆ orientedGauss() [1/2]

std::string regina::Tangle::orientedGauss ( ) const

Outputs an oriented Gauss code for this tangle.

Oriented Gauss codes for tangles are an extension of oriented Gauss codes for knots. Whilst oriented Gauss codes for knots are used elsewhere (they are based on a format used by Andreeva et al.), these codes for tangles are specific to Regina (so you should not expect other software to understand them).

For a full explanation of how oriented Gauss codes work for tangles, see the documentation for fromOrientedGauss(const std::string&), which imports tangles in this format.

The string that is returned will not contain any newlines.

Note
There is another variant of this routine that, instead of returning a string, writes directly to an output stream.
Returns
an oriented Gauss code for this tangle.

◆ orientedGauss() [2/2]

void regina::Tangle::orientedGauss ( std::ostream &  out) const


Writes an oriented Gauss code for this tangle to the given output stream.

Oriented Gauss codes for tangles are an extension of oriented Gauss codes for knots. Whilst oriented Gauss codes for knots are used elsewhere (they are based on a format used by Andreeva et al.), these codes for tangles are specific to Regina (so you should not expect other software to understand them).

For a full explanation of how oriented Gauss codes work for tangles, see the documentation for fromOrientedGauss(const std::string&), which imports tangles in this format.

The output will not contain any newlines.

Note
There is another variant of this routine that, instead of using an output stream, simply returns a string.
Python
This routine is not available in Python. Instead, Python users can use the variant orientedGauss(), which takes no arguments and returns the output as a string.
Parameters
outthe output stream to which to write.

◆ r1()

bool regina::Tangle::r1 ( Crossing crossing,
bool  check = true,
bool  perform = true 
)

Tests for and/or performs a type I Reidemeister move to remove a crossing.

Unlike links, which implement the full suite of Reidemeister moves, tangles (at present) only offer the simplifying versions of Reidemeister moves I and II.

The behaviour of this routine is identical to the r1() routine in the Link class; see Link::r1() for further details.

Precondition
If perform is true but check is false, then it must be known in advance that this move can be performed at the given location.
The given crossing is either a null pointer, or else some crossing in this tangle.
Parameters
crossingidentifies the crossing to be removed.
checktrue if we are to check whether the move can be performed at the given location.
performtrue if we should actually perform the move.
Returns
If check is true, this function returns true if and only if the move can be performed. If check is false, this function always returns true.

◆ r2() [1/2]

bool regina::Tangle::r2 ( StrandRef  arc,
bool  check = true,
bool  perform = true 
)

Tests for and/or performs a type II Reidemeister move to remove two crossings.

Unlike links, which implement the full suite of Reidemeister moves, tangles (at present) only offer the simplifying versions of Reidemeister moves I and II.

The behaviour of this routine is identical to the r2() routine in the Link class; see Link::r2() for further details.

Precondition
If perform is true but check is false, then it must be known in advance that this move can be performed at the given location.
The given strand reference is either a null reference, or else refers to some strand of some crossing in this tangle.
Parameters
arcidentifies one of the arcs of the bigon about which the move will be performed.
checktrue if we are to check whether the move is legal.
performtrue if we should actually perform the move.
Returns
If check is true, this function returns true if and only if the requested move is legal. If check is false, this function always returns true.

◆ r2() [2/2]

bool regina::Tangle::r2 ( Crossing crossing,
bool  check = true,
bool  perform = true 
)
inline

Tests for and/or performs a type II Reidemeister move to remove two crossings.

Unlike links, which implement the full suite of Reidemeister moves, tangles (at present) only offer the simplifying versions of Reidemeister moves I and II.

The behaviour of this routine is identical to the r2() routine in the Link class; see Link::r2() for further details.

Precondition
If perform is true but check is false, then it must be known in advance that this move can be performed at the given location.
The given crossing is either a null pointer, or else some crossing in this tangle.
Parameters
crossingidentifies the crossing at the beginning of the "upper" arc that features in this move.
checktrue if we are to check whether the move is legal.
performtrue if we should actually perform the move.
Returns
If check is true, this function returns true if and only if the requested move is legal. If check is false, this function always returns true.

◆ simplifyToLocalMinimum()

bool regina::Tangle::simplifyToLocalMinimum ( bool  perform = true)

Uses type I and II Reidemeister moves to reduce the tangle monotonically to some local minimum number of crossings.

Type III Reidemeister moves (which do not reduce the number of crossings) are not used in this routine.

Unlike links, tangle do not (at present) offer stronger simplification routines (such as the much better Link::intelligentSimplify() and Link::simplifyExhaustive()).

Warning
The implementation of this routine (and therefore its results) may change between different releases of Regina.
Parameters
performtrue if we are to perform the simplifications, or false if we are only to investigate whether simplifications are possible (defaults to true).
Returns
if perform is true, this routine returns true if and only if the link was changed to reduce the number of crossings; if perform is false, this routine returns true if and only if it determines that it is capable of performing such a change.

◆ size()

size_t regina::Tangle::size ( ) const
inline

Returns the number of crossings in this tangle.

Returns
the number of crossings.

◆ str()

std::string regina::Output< Tangle , false >::str ( ) const
inherited


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
In addition to str(), this is also used as the Python "stringification" function __str__().
Returns
a short text representation of this object.

◆ swapContents()

void regina::Tangle::swapContents ( Tangle other)

Swaps the contents of this and the given tangle.

All crossings that belong to this link will be moved to other, and all crossings that belong to other will be moved to this link. Likewise, all cached properties (e.g., tree decompositions) will be swapped.

In particular, any Crossing pointers or references and any StrandRef objects will remain valid.

This routine will behave correctly if other is in fact this link.

Parameters
otherthe link whose contents should be swapped with this.

◆ translate()

StrandRef regina::Tangle::translate ( const StrandRef other) const
inline

Translates a strand reference for some other tangle into the corresponding strand reference for this tangle.

Specifically: if other refers to some strand (upper or lower) of crossing number k of some other tangle, then the return value will refer to the same strand (upper or lower) of crossing number k of this tangle.

This routine behaves correctly even if other is a null reference.

Parameters
otherthe strand reference to translate.
Returns
the corresponding strand reference for this tangle.

◆ turn()

void regina::Tangle::turn ( int  direction = 1)

Rotates this tangle by 90 degrees.

Parameters
directioneither 1 if the tangle should be rotated clockwise, or -1 if the tangle should be rotated anticlockwise.

◆ twist()

void regina::Tangle::twist ( int  sign = 1)

Adds a twist to the right-hand end of this tangle.

Parameters
signeither 1 if we should perform a positive twist (dragging the bottom-right endpoint up over the top-right endpoint), or -1 if we should perform a negative twist (dragging the bottom-right endpoint up beneath the top-right endpoint).

◆ type()

char regina::Tangle::type ( ) const
inline

Returns the type of this tangle.

This will be one of the characters -, | or x, indicating a horizontal, vertical or diagonal type as described in the class notes.

Returns
the type of this crossing.

◆ utf8()

std::string regina::Output< Tangle , false >::utf8 ( ) const
inherited

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.

◆ writeTextLong()

void regina::Tangle::writeTextLong ( std::ostream &  out) const


Writes a detailed text representation of this tangle to the given output stream.

Python
Not present.
Parameters
outthe output stream to which to write.

◆ writeTextShort()

void regina::Tangle::writeTextShort ( std::ostream &  out) const


Writes a short text representation of this tangle to the given output stream.

Python
Not present.
Parameters
outthe output stream to which to write.

The documentation for this class was generated from the following file:

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