Regina Calculation Engine
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Friends | List of all members
regina::Link Class Referenceabstract

Represents a directed knot or link in the 3-sphere. More...

#include <link/link.h>

Inheritance diagram for regina::Link:
regina::Packet regina::Output< Packet > regina::SafePointeeBase< Packet >

Public Types

typedef Packet SafePointeeType
 The type of object being pointed to. More...
 

Public Member Functions

bool hasOwner () const
 Indicates whether some other object in the calculation engine is responsible for ultimately destroying this object. More...
 
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...
 
bool hasSafePtr () const
 Is there one or more SafePtr currently pointing to this object? More...
 
Constructors and Destructors
 Link ()
 Constructs an empty link. More...
 
 Link (size_t unknots)
 Constructs the unlink with the given number of components. More...
 
 Link (const Link &copy)
 Constructs a new copy of the given link. More...
 
 Link (const Link &copy, bool cloneProps)
 Constructs a new copy of the given link, with the option of whether or not to clone its computed properties also. More...
 
 Link (const std::string &description)
 "Magic" constructor that tries to find some way to interpret the given string as a link. More...
 
 ~Link ()
 Destroys this link. More...
 
Crossings and Components
bool isEmpty () const
 Determines whether this link is empty. More...
 
size_t size () const
 Returns the number of crossings in this link. More...
 
size_t countComponents () const
 Returns the number of components in this link. More...
 
Crossingcrossing (size_t index) const
 Returns a pointer to the crossing at the given index within this link. More...
 
StrandRef component (size_t index) const
 Returns a strand in the given component of this link. More...
 
StrandRef strand (int id) const
 Returns the strand in the link with the given integer ID. More...
 
StrandRef translate (const StrandRef &other) const
 Translates a strand reference for some other link into the corresponding strand reference for this link. More...
 
bool connected (const Crossing *a, const Crossing *b) const
 Determines whether the two given crossings are connected in the underlying 4-valent graph of the link diagram. More...
 
Editing
void swapContents (Link &other)
 Swaps the contents of this and the given link. More...
 
void change (Crossing *c)
 Switches the upper and lower strands of the given crossing. More...
 
void changeAll ()
 Switches the upper and lower strands of every crossing in the diagram. More...
 
void resolve (Crossing *c)
 Resolves the given crossing. More...
 
void reflect ()
 Converts this link into its reflection. More...
 
void rotate ()
 Rotates this link diagram, converting it into a different diagram of the same link. More...
 
void reverse ()
 Reverses the orientation of every component of this link. 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 r1 (StrandRef arc, int side, int sign, bool check=true, bool perform=true)
 Tests for and/or performs a type I Reidemeister move to add a new 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 r2 (StrandRef upperArc, int upperSide, StrandRef lowerArc, int lowerSide, bool check=true, bool perform=true)
 Tests for and/or performs a type II Reidemeister move to add two new crossings. More...
 
bool r3 (StrandRef arc, int side, bool check=true, bool perform=true)
 Tests for and/or performs a type III Reidemeister move. More...
 
bool r3 (Crossing *crossing, int side, bool check=true, bool perform=true)
 Tests for and/or performs a type III Reidemeister move. More...
 
bool hasReducingPass () const
 Tests whether this knot has a pass move that will reduce the number of crossings. More...
 
bool intelligentSimplify ()
 Attempts to simplify the link diagram using fast and greedy heuristics. More...
 
bool simplifyToLocalMinimum (bool perform=true)
 Uses type I and II Reidemeister moves to reduce the link monotonically to some local minimum number of crossings. More...
 
bool simplifyExhaustive (int height=1, unsigned nThreads=1, ProgressTrackerOpen *tracker=nullptr)
 Attempts to simplify this knot diagram using a slow but exhaustive search through the Reidemeister graph. More...
 
template<typename Action , typename... Args>
bool rewrite (int height, unsigned nThreads, ProgressTrackerOpen *tracker, Action &&action, Args &&... args) const
 
Explores all knot diagrams that can be reached from this via Reidemeister moves, without exceeding a given number of additional crossings. More...
 
void composeWith (const Link &other)
 Forms the composition of this with the given link. More...
 
Invariants and Related Properties
bool isAlternating () const
 Returns whether this knot diagram is alternating. More...
 
long linking () const
 Returns the linking number of this link. More...
 
long writhe () const
 Returns the writhe of this link diagram. More...
 
Triangulation< 3 > * complement (bool simplify=true) const
 Returns an ideal triangulation of the complement of this link in the 3-sphere. More...
 
Linkparallel (int k, Framing framing=FRAMING_SEIFERT) const
 Returns k cables of this link, all parallel to each other using the given framing. More...
 
const Laurent< Integer > & bracket (Algorithm alg=ALG_DEFAULT, ProgressTracker *tracker=nullptr) const
 Returns the Kauffman bracket polynomial of this link diagram. More...
 
bool knowsBracket () const
 Is the Kauffman bracket polynomial of this link diagram already known? See bracket() for further details. More...
 
const Laurent< Integer > & jones (Algorithm alg=ALG_DEFAULT, ProgressTracker *tracker=nullptr) const
 Returns the Jones polynomial of this link, but with all exponents doubled. More...
 
bool knowsJones () const
 Is the Jones polynomial of this link diagram already known? See jones() for further details. More...
 
const Laurent2< Integer > & homflyAZ (Algorithm alg=ALG_DEFAULT, ProgressTracker *tracker=nullptr) const
 Returns the HOMFLY polynomial of this link, as a polynomial in alpha and z. More...
 
const Laurent2< Integer > & homflyLM (Algorithm alg=ALG_DEFAULT, ProgressTracker *tracker=nullptr) const
 Returns the HOMFLY polynomial of this link, as a polynomial in l and m. More...
 
const Laurent2< Integer > & homfly (Algorithm alg=ALG_DEFAULT, ProgressTracker *tracker=nullptr) const
 Returns the HOMFLY polynomial of this link, as a polynomial in alpha and z. More...
 
bool knowsHomfly () const
 Is the HOMFLY polynomial of this link diagram already known? See homflyAZ() and homflyLM() for further details. More...
 
const TreeDecompositionniceTreeDecomposition () const
 Returns a nice tree decomposition of the planar 4-valent multigraph formed by this link diagram. More...
 
void useTreeDecomposition (const TreeDecomposition &td)
 Instructs Regina to use the given tree decomposition as the starting point whenever it needs a tree decomposition for this link. More...
 
Packet Administration
virtual void writeTextShort (std::ostream &out) const override
 
Writes a short text representation of this object to the given output stream. More...
 
virtual void writeTextLong (std::ostream &out) const override
 
Writes a detailed text representation of this object to the given output stream. More...
 
virtual bool dependsOnParent () const override
 Determines if this packet depends upon its parent. More...
 
Exporting Links
std::string brief () const
 Outputs this link in Regina's own brief format. More...
 
std::string gauss () const
 Outputs a classical Gauss code for this knot. More...
 
void gauss (std::ostream &out) const
 
Writes a classical Gauss code for this knot to the given output stream. More...
 
std::string orientedGauss () const
 Outputs an oriented Gauss code for this knot. More...
 
void orientedGauss (std::ostream &out) const
 
Writes an oriented Gauss code for this knot to the given output stream. More...
 
std::string jenkins () const
 Exports this link as a string using the text representation described by Bob Jenkins. More...
 
void jenkins (std::ostream &out) const
 
Exports this link to the given output stream using the text representation described by Bob Jenkins. More...
 
std::string dt (bool alpha=false) const
 Outputs this knot using Dowker-Thistlethwaite notation. More...
 
void dt (std::ostream &out, bool alpha=false) const
 
Writes this knot to the given output stream using Dowker-Thistlethwaite notation. More...
 
void writePACE (std::ostream &out) const
 
Outputs the underlying planar 4-valent multigraph using the PACE text format. More...
 
std::string pace () const
 Returns a text representation of the underlying planar 4-valent multigraph, using the PACE text format. More...
 
std::string dumpConstruction () const
 Returns C++ code that can be used to reconstruct this link. More...
 
std::string knotSig (bool useReflection=true, bool useReversal=true) const
 Constructs the signature for this knot diagram. More...
 
Packet Identification
virtual PacketType type () const =0
 Returns the unique integer ID representing this type of packet. More...
 
virtual std::string typeName () const =0
 Returns an English name for this type of packet. More...
 
const std::string & label () const
 Returns the label associated with this individual packet. More...
 
std::string humanLabel () const
 Returns the label associated with this individual packet, adjusted if necessary for human-readable output. More...
 
std::string adornedLabel (const std::string &adornment) const
 Returns the label of this packet adorned with the given string. More...
 
void setLabel (const std::string &label)
 Sets the label associated with this individual packet. More...
 
std::string fullName () const
 Returns a descriptive text string for the packet. More...
 
Tags
bool hasTag (const std::string &tag) const
 Determines whether this packet has the given associated tag. More...
 
bool hasTags () const
 Determines whether this packet has any associated tags at all. More...
 
bool addTag (const std::string &tag)
 Associates the given tag with this packet. More...
 
bool removeTag (const std::string &tag)
 Removes the association of the given tag with this packet. More...
 
void removeAllTags ()
 Removes all associated tags from this packet. More...
 
const std::set< std::string > & tags () const
 
Returns the set of all tags associated with this packet. More...
 
Event Handling
bool listen (PacketListener *listener)
 Registers the given packet listener to listen for events on this packet. More...
 
bool isListening (PacketListener *listener)
 Determines whether the given packet listener is currently listening for events on this packet. More...
 
bool unlisten (PacketListener *listener)
 Unregisters the given packet listener so that it no longer listens for events on this packet. More...
 
Tree Queries
Packetparent () const
 Determines the parent packet in the tree structure. More...
 
PacketfirstChild () const
 Determines the first child of this packet in the tree structure. More...
 
PacketlastChild () const
 Determines the last child of this packet in the tree structure. More...
 
PacketnextSibling () const
 Determines the next sibling of this packet in the tree structure. More...
 
PacketprevSibling () const
 Determines the previous sibling of this packet in the tree structure. More...
 
Packetroot () const
 Determines the root of the tree to which this packet belongs. More...
 
unsigned levelsDownTo (const Packet *descendant) const
 Counts the number of levels between this packet and its given descendant in the tree structure. More...
 
unsigned levelsUpTo (const Packet *ancestor) const
 Counts the number of levels between this packet and its given ancestor in the tree structure. More...
 
bool isGrandparentOf (const Packet *descendant) const
 Determines if this packet is equal to or an ancestor of the given packet in the tree structure. More...
 
size_t countChildren () const
 Returns the number of immediate children of this packet. More...
 
size_t countDescendants () const
 Returns the total number of strict descendants of this packet. More...
 
size_t totalTreeSize () const
 Determines the total number of packets in the tree or subtree for which this packet is matriarch. More...
 
Tree Manipulation
void insertChildFirst (Packet *child)
 
Inserts the given packet as the first child of this packet. More...
 
void insertChildLast (Packet *child)
 
Inserts the given packet as the last child of this packet. More...
 
void insertChildAfter (Packet *newChild, Packet *prevChild)
 
Inserts the given packet as a child of this packet at the given location in this packet's child list. More...
 
void makeOrphan ()
 
Cuts this packet away from its parent in the tree structure and instead makes it matriarch of its own tree. More...
 
void reparent (Packet *newParent, bool first=false)
 
Cuts this packet away from its parent in the tree structure, and inserts it as a child of the given packet instead. More...
 
void transferChildren (Packet *newParent)
 Cuts all of this packet's children out of the packet tree, and reinserts them as children of the given packet instead. More...
 
void swapWithNextSibling ()
 Swaps this packet with its next sibling in the sequence of children beneath their common parent packet. More...
 
void moveUp (unsigned steps=1)
 Moves this packet the given number of steps towards the beginning of its sibling list. More...
 
void moveDown (unsigned steps=1)
 Moves this packet the given number of steps towards the end of its sibling list. More...
 
void moveToFirst ()
 Moves this packet to be the first in its sibling list. More...
 
void moveToLast ()
 Moves this packet to be the last in its sibling list. More...
 
void sortChildren ()
 Sorts the immediate children of this packet according to their packet labels. More...
 
Searching and Iterating
SubtreeIterator begin ()
 
Returns an iterator at the beginning of the range of packets in the subtree rooted at this packet. More...
 
SubtreeIterator end ()
 
Returns an iterator beyond the end of the range of packets in the subtree rooted at this packet. More...
 
PacketDescendants descendants () const
 Returns a lightweight object for iterating through all strict descendants of this packet in the packet tree. More...
 
PacketChildren children () const
 Returns a lightweight object for iterating through the immediate children of this packet. More...
 
PacketnextTreePacket ()
 Finds the next packet after this in a complete depth-first iteration of the entire tree structure to which this packet belongs. More...
 
const PacketnextTreePacket () const
 Finds the next packet after this in a complete depth-first iteration of the entire tree structure to which this packet belongs. More...
 
PacketnextTreePacket (const std::string &type)
 Finds the next packet after this of the requested type in a complete depth-first iteration of the entire tree structure. More...
 
const PacketnextTreePacket (const std::string &type) const
 Finds the next packet after this of the requested type in a complete depth-first iteration of the entire tree structure. More...
 
PacketfirstTreePacket (const std::string &type)
 Finds the first packet of the requested type in a complete depth-first iteration of the tree structure. More...
 
const PacketfirstTreePacket (const std::string &type) const
 Finds the first packet of the requested type in a complete depth-first iteration of the tree structure. More...
 
PacketfindPacketLabel (const std::string &label)
 Finds the packet with the requested label in the tree or subtree for which this packet is matriarch. More...
 
const PacketfindPacketLabel (const std::string &label) const
 Finds the packet with the requested label in the tree or subtree for which this packet is matriarch. More...
 
Packet Dependencies
bool isPacketEditable () const
 Determines whether this packet can be altered without invalidating or otherwise upsetting any of its immediate children. More...
 
Cloning
Packetclone (bool cloneDescendants=false, bool end=true) const
 Clones this packet (and possibly its descendants), assigns to it a suitable unused label and inserts the clone into the tree as a sibling of this packet. More...
 
File I/O
bool save (const char *filename, bool compressed=true) const
 
Saves the subtree rooted at this packet to the given Regina data file, using Regina's native XML file format. More...
 
bool save (std::ostream &s, bool compressed=true) const
 
Writes the subtree rooted at this packet to the given output stream, in the format of a Regina XML data file. More...
 
void writeXMLFile (std::ostream &out) const
 
Writes the subtree rooted at this packet to the given output stream in Regina's native XML file format. More...
 
std::string internalID () const
 Returns a unique string ID that identifies this packet. More...
 

Static Public Member Functions

static XMLPacketReaderxmlReader (Packet *parent, XMLTreeResolver &resolver)
 
Constructors and Destructors
static void safeDelete (Packet *p)
 
Either destroys or orphans the given packet, according to whether it has safe pointers that currently reference it. More...
 

Static Public Attributes

static const char * jonesVar
 The name of the variable used in the Jones polynomial, as returned by jones(). More...
 
static const char * homflyAZVarX
 The name of the first variable used in the variant of the HOMFLY polynomial as returned by homflyAZ(). More...
 
static const char * homflyAZVarY
 The name of the second variable used in the variant of the HOMFLY polynomial as returned by homflyAZ(). More...
 
static const char * homflyLMVarX
 The name of the first variable used in the variant of the HOMFLY polynomial as returned by homflyLM(). More...
 
static const char * homflyLMVarY
 The name of the second variable used in the variant of the HOMFLY polynomial as returned by homflyLM(). More...
 
static const char * homflyVarX
 The name of the first variable used in the variant of the HOMFLY polynomial as returned by homfly(). More...
 
static const char * homflyVarY
 The name of the second variable used in the variant of the HOMFLY polynomial as returned by homfly(). More...
 

Protected Member Functions

virtual PacketinternalClonePacket (Packet *parent) const override
 Makes a newly allocated copy of this packet. More...
 
virtual void writeXMLPacketData (std::ostream &out) const override
 Writes a chunk of XML containing the data for this packet only. More...
 
void writeXMLPacketTree (std::ostream &out) const
 Writes a chunk of XML containing the subtree with this packet as matriarch. More...
 

Friends

class ModelLinkGraph
 
class Tangle
 
class XMLLinkCrossingsReader
 
class XMLLinkComponentsReader
 

Building Links

void insertTorusLink (int p, int q, bool positive=true)
 Inserts a new (p, q) torus link into this link. More...
 
template<typename... Args>
static LinkfromData (std::initializer_list< int > crossingSigns, std::initializer_list< Args >... components)
 
Creates a new link from hard-coded information about its crossings and components. More...
 
static LinkfromKnotSig (const std::string &sig)
 Recovers a knot diagram from its signature. More...
 
static LinkfromGauss (const std::string &str)
 Creates a new knot from a classical Gauss code. More...
 
template<typename Iterator >
static LinkfromGauss (Iterator begin, Iterator end)
 
Creates a new knot from a classical Gauss code. More...
 
static LinkfromOrientedGauss (const std::string &str)
 Creates a new knot from an "oriented" variant of the Gauss code. More...
 
template<typename Iterator >
static LinkfromOrientedGauss (Iterator begin, Iterator end)
 
Creates a new knot from an "oriented" variant of the Gauss code. More...
 
static LinkfromJenkins (const std::string &str)
 Builds a link from the text representation described by Bob Jenkins. More...
 
static LinkfromJenkins (std::istream &in)
 
Builds a link from the text representation described by Bob Jenkins. More...
 
static LinkfromDT (const std::string &str)
 Creates a new knot from either alphabetical or numerical Dowker-Thistlethwaite notation. More...
 
template<typename Iterator >
static LinkfromDT (Iterator begin, Iterator end)
 
Creates a new knot from an integer sequence using the numerical variant of Dowker-Thistlethwaite notation. More...
 

Detailed Description

Represents a directed knot or link in the 3-sphere.

This class supports links with any number of components (including zero), and it also supports components with no crossings (which form additional unknot components of the overall link).

Member Typedef Documentation

◆ SafePointeeType

The type of object being pointed to.

Constructor & Destructor Documentation

◆ Link() [1/5]

regina::Link::Link ( )
inline

Constructs an empty link.

This will have zero components.

◆ Link() [2/5]

regina::Link::Link ( size_t  unknots)
inline

Constructs the unlink with the given number of components.

Parameters
unknotsthe number of (unknotted) components in the new unlink.

◆ Link() [3/5]

regina::Link::Link ( const Link copy)
inline

Constructs a new copy of the given link.

The packet tree structure and packet label are not copied.

This will clone any computed properties (such as Jones polynomial and so on) of the given link also. If you want a "clean" copy that resets all properties to unknown, you can use the two-argument copy constructor instead.

Parameters
copythe link to copy.

◆ Link() [4/5]

regina::Link::Link ( const Link copy,
bool  cloneProps 
)

Constructs a new copy of the given link, with the option of whether or not to clone its computed properties also.

Parameters
copythe link to copy.
clonePropstrue if this should also clone any computed properties of the given link (such as Jones polynomial and so on), or false if the new link should have all properties marked as unknown.

◆ Link() [5/5]

regina::Link::Link ( const std::string &  description)

"Magic" constructor that tries to find some way to interpret the given string as a link.

At present, Regina understands the following types of strings (and attempts to parse them in the following order):

This list may grow in future versions of Regina.

Regina will also set the packet label accordingly.

If Regina cannot interpret the given string, this will be left as the empty link.

Parameters
descriptiona string that describes a knot or link.

◆ ~Link()

regina::Link::~Link ( )
inline

Destroys this link.

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

Member Function Documentation

◆ bracket()

const Laurent<Integer>& regina::Link::bracket ( Algorithm  alg = ALG_DEFAULT,
ProgressTracker tracker = nullptr 
) const

Returns the Kauffman bracket polynomial of this link diagram.

Note that the bracket polynomial is not an invariant - it is preserved under Reidemeister moves II and III, but not I.

If this is the empty link, then this routine will return the zero polynomial.

Bear in mind that each time the link changes, all of its polynomials will be deleted. Thus the reference that is returned from this routine should not be kept for later use. Instead, bracket() should be called again; this will be instantaneous if the bracket polynomial has already been calculated.

If this polynomial has already been computed, then the result will be cached and so this routine will be very fast (since it just returns the previously computed result). Otherwise the computation could be quite slow, particularly for larger numbers of crossings. This (potentially) long computation can be managed by passing a progress tracker:

  • If a progress tracker is passed and the polynomial has not yet been computed, then the calculation will take place in a new thread and this routine will return immediately. Once the progress tracker indicates that the calculation has finished, you can call bracket() again to retrieve the polynomial.
  • If no progress tracker is passed and the polynomial has not yet been computed, the calculation will run in the current thread and this routine will not return until it is complete.
  • If the requested invariant has already been computed, then this routine will return immediately with the pre-computed value. If a progress tracker is passed then it will be marked as finished.
Warning
The naive algorithm can only handle a limited number of crossings (currently less than the number of bits in a long, which on a typical machine is 64). If you pass ALG_NAIVE and you have too many crossings (which is not advised, since the naive algorithm requires 2^n time), then this routine will ignore your choice of algorithm and use the treewidth-based algorithm regardless.
Parameters
algthe algorithm with which to compute the polynomial. If you are not sure, the default (ALG_DEFAULT) is a safe choice. If you wish to specify a particular algorithm, there are currently two choices: ALG_NAIVE is a slow algorithm that computes the Kauffman bracket by resolving all crossings in all possible ways, and ALG_TREEWIDTH uses a fixed-parameter tractable treewidth-based algorithm.
trackera progress tracker through which progress will be reported, or null if no progress reporting is required.
Returns
the bracket polynomial. If a progress tracker was passed then this return value must be ignored, and you should call bracket() again once the tracker is marked as finished.

◆ brief()

std::string regina::Link::brief ( ) const

Outputs this link in Regina's own brief format.

This format is concise, but contains enough information to reconstruct the link.

This format cannot (yet) be used to read links back into Regina, and so it is not good for external storage, or for passing links between different programs (or even different instances of Regina). It was originally designed for use with the test suite, where it was used to ensure that links with being created and/or manipulated correctly.

The output will contains the following elements, separated by single spaces:

  • a sequence of signs (+ or -), concatenated together, giving the signs of the crossings in order from crossing 0 to crossing size()-1;
  • a description of each component of the link, in order from component 0 to component countComponents()-1. Each component will be written in the form ( a b c ... ), indicating the crossings that are encountered as we follow the component in the forward direction from its starting strand. Each element a, b, c and so on will be written in the format used by the StrandRef class: either ^n when passing over crossing n, or _n when passing under crossing n.

For example, the Whitehead link as returned by ExampleLink.whitehead() will give the following brief output:

--++- ( ^0 _1 ^4 _3 ^2 _4 ) ( _0 ^1 _2 ^3 )

As a special case, if the link contains no crossings, then the format will not begin with a space; instead it will simply be a sequence of the form ( ) ( ) ... ( ).

The string will not end in a newline.

Returns
a description of this link in Regina's brief format.

◆ change()

void regina::Link::change ( Crossing c)

Switches the upper and lower strands of the given crossing.

Parameters
cthe crossing to change.

◆ changeAll()

void regina::Link::changeAll ( )

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

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

◆ complement()

Triangulation<3>* regina::Link::complement ( bool  simplify = true) const

Returns an ideal triangulation of the complement of this link in the 3-sphere.

The triangulation will have one ideal vertex for each link component. Assuming you pass simplify as true (the default), there will typically be no internal vertices; however, this is not guaranteed.

Initially, the triangulation will be oriented. In particular, each tetrahedron will be oriented according to a right-hand rule: the thumb of the right hand points from vertices 0 to 1, and the fingers curl around to point from vertices 2 to 3.

What happens next depends upon the argument simplify:

  • If you pass simplify as true, then Regina will attempt to simplify the triangulation to as few tetrahedra as possible. As a result, the orientation described above will be lost.
  • If you pass simplify as false, then Regina will leave the triangulation as is. This will preserve the orientation, but it means that the triangulation will contain both ideal and internal vertices (and, in general, far more tetrahedra than are necessary).

The triangulation will be newly created, and it is the responsibility of the caller of this routine to destroy it.

Parameters
simplifytrue if and only if the triangulation of the complement should be simplified (thereby losing information about the orientation), as described above.
Returns
the complement of this link, as a newly-created object.

◆ component()

StrandRef regina::Link::component ( size_t  index) const
inline

Returns a strand in the given component of this link.

For each component of the link, this routine returns a "starting strand". You can traverse the entire component by beginning at this starting strand and repeatedly incrementing it through a routine such as StrandRef::operator++ or StrandRef::next().

If a component has no crossings (which means it must be a separate unknot component), then this routine will return a null reference (i.e., StrandRef::crossing() will return null).

Parameters
indexthe index of the requested component. This must be between 0 and countComponents()-1 inclusive.
Returns
a "starting strand" for traversing the component at the given index, or a null reference if the requested component has no crossings.

◆ composeWith()

void regina::Link::composeWith ( const Link other)

Forms the composition of this with the given link.

This link will be altered directly.

Specifically, the first component of the given link will be grafted into the first component of this link, in a way that preserves orientations and crossing signs. If the given link has any additional components, then they will be copied into this link directly with no modification.

This routine may be expanded in future versions of Regina to allow more flexibility (in particular, to allow you to choose which components of the two links to graft together, and/or at which strands to graft them).

If either link is empty (i.e., contains no components at all), then the result will simply be a clone of the other link (with no composition operation performed).

It is allowed to pass this link as other.

Parameters
otherthe link with which this should be composed.

◆ connected()

bool regina::Link::connected ( const Crossing a,
const Crossing b 
) const

Determines whether the two given crossings are connected in the underlying 4-valent graph of the link diagram.

Here "the underlying 4-valent graph" means the multigraph whose vertices are the crossings and whose edges are the arcs between crossings. In particular

  • two crossings may be connected even if they involve entirely different components of the link;
  • if two crossings are not connected then the underlying link must be splittable (though this need not happen in the other direction: one can have a diagram of a splittable link in which all crossings are connected with each other).
Warning
This routine is slow (linear time), since it may need to perform a depth-first search through the graph.
Parameters
athe first of the two crossings to examine.
bthe second of the two crossings to examine.
Returns
true if and only if the two given crossings are connected.

◆ countComponents()

size_t regina::Link::countComponents ( ) const
inline

Returns the number of components in this link.

Returns
the number of components.

◆ crossing()

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

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

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

◆ dependsOnParent()

bool regina::Link::dependsOnParent ( ) const
inlineoverridevirtual

Determines if this packet depends upon its parent.

This is true if the parent cannot be altered without invalidating or otherwise upsetting this packet.

Returns
true if and only if this packet depends on its parent.

Implements regina::Packet.

◆ detail()

std::string regina::Output< Packet , 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.

◆ dt() [1/2]

std::string regina::Link::dt ( bool  alpha = false) const

Outputs this knot using Dowker-Thistlethwaite notation.

For an n-crossing knot, Regina supports two variants of this notation:

  • a numerical variant (the default), which is a sequence of n even signed integers as described (amongst other places) in Section 2.2 of C. C. Adams, "The knot book", W. H. Freeman & Co., 1994;
  • an alphabetical variant, which transforms the numerical notation into a sequence of letters by replacing positive integers (2,4,6,...) with lower-case letters (a,b,c,...), and replacing negative integers (-2,-4,-6,...) with upper-case letters (A,B,C,...). This alphabetical variant can only be used for knots with 26 crossings or fewer; for larger knots this routine will return the empty string if the alphabetical variant is requested.

In general, Dowker-Thistlethwaite notation does not carry enough information to uniquely reconstruct the knot. For instance, both a knot and its reflection can be described by the same sequence of integers; moreover, for composite knots, the same Dowker-Thistlethwaite notation can describe inequivalent knots (even when allowing for reflections). If you need notation that specifies the knot uniquely, consider using the oriented Gauss code instead, as output by orientedGauss().

Currently Regina only supports Dowker-Thistlethwaite notation for knots, not multiple-component links. If this link does not have precisely one component then the empty string will be returned.

The string 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.
Parameters
alphatrue to use alphabetical notation, or false (the default) to use numerical notation.
Returns
the Dowker-Thistlethwaite notation for this knot diagram. This routine will return the empty string if this link has zero or multiple components, or if alpha is true and the knot has more than 26 crossings.

◆ dt() [2/2]

void regina::Link::dt ( std::ostream &  out,
bool  alpha = false 
) const


Writes this knot to the given output stream using Dowker-Thistlethwaite notation.

For an n-crossing knot, Regina supports two variants of this notation:

  • a numerical variant (the default), which is a sequence of n even signed integers as described (amongst other places) in Section 2.2 of C. C. Adams, "The knot book", W. H. Freeman & Co., 1994;
  • an alphabetical variant, which transforms the numerical notation into a sequence of letters by replacing positive integers (2,4,6,...) with lower-case letters (a,b,c,...), and replacing negative integers (-2,-4,-6,...) with upper-case letters (A,B,C,...). This alphabetical variant can only be used for knots with 26 crossings or fewer; for larger knots this routine will output nothing at all if the alphabetical variant is requested.

In general, Dowker-Thistlethwaite notation does not carry enough information to uniquely reconstruct the knot. For instance, both a knot and its reflection can be described by the same sequence of integers; moreover, for composite knots, the same Dowker-Thistlethwaite notation can describe inequivalent knots (even when allowing for reflections). If you need notation that specifies the knot uniquely, consider using the oriented Gauss code instead, as output by orientedGauss().

Currently Regina only supports Dowker-Thistlethwaite notation for knots, not multiple-component links. If this link does not have precisely one component then nothing will be output at all.

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 dt(), which takes just the optional alpha argument and returns the output as a string.
Parameters
outthe output stream to which to write.
alphatrue to use alphabetical notation, or false (the default) to use numerical notation.

◆ dumpConstruction()

std::string regina::Link::dumpConstruction ( ) const

Returns C++ code that can be used to reconstruct this link.

This code will use the Link constructor that takes a series of hard-coded C++11 initialiser lists.

The main purpose of this routine is to generate these hard-coded initialiser lists, which can be tedious and error-prone to write by hand.

Returns
the C++ code that was generated.

◆ fromData()

template<typename... Args>
static Link* regina::Link::fromData ( std::initializer_list< int >  crossingSigns,
std::initializer_list< Args >...  components 
)
static


Creates a new link from hard-coded information about its crossings and components.

This constructor takes a series of C++11 initialiser lists (each a list of integers), which makes it useful for creating hard-coded examples directly in C++ code.

For the purposes of this routine, we number the crossings 1, 2, ..., n. The lists that you must pass to this routine are as follows:

  • The first list contains the signs of crossings 1, ..., n in order, where each sign is either +1 or -1.
  • Each subsequent list describes a single component of the link. The list identifies which crossings you visit in order when traversing the component; a positive entry i indicates that you pass over crossing i, and a negative entry -i indicates that you pass under crossing i. Empty lists are allowed (these denote separate unknot components).
  • If a component has no crossings, then you should pass the list { 0 }, not the empty list. (This is because the C++ compiler cannot deduce the type of an empty list.)

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

As an example, you can construct the left-hand trefoil and the Hopf link as follows:

trefoil = Link::fromData({ -1, -1, -1 }, { 1, -2, 3, -1, 2, -3 });
hopf = Link::fromData({ +1, +1 }, { 1, -2 }, { -1, 2 });

The topology of the link is defined precisely by this data, but the precise embedding of the diagram in the plane remains ambiguous. To be exact: the embedding of the diagram in the 2-sphere is defined precisely, but there remains a choice of which 2-cell of this embedding will contain the point at infinity (i.e., which 2-cell becomes the exterior cell of the diagram in the plane).

Warning
While this routine does some error checking on the input, it does not test for planarity of the diagram. That is, if the input describes a link diagram that must be drawn on some higher-genus surface as opposed to the plane, this will not be detected. Of course such inputs are not allowed, and it is currently up to the user to enforce this.
Note
If you have an existing link that you would like to hard-code, the routine dumpConstruction() will output C++ code that can reconstruct the link by calling this constructor.
Python
Not available.
Parameters
crossingSignsa list containing the signs of the crossings; each sign must be either +1 or -1.
componentsone list for each link component that describes the crossings that are visited along that component, as described in the detailed notes above.
Returns
a newly constructed link, or null if the input was found to be invalid.

◆ fromDT() [1/2]

static Link* regina::Link::fromDT ( const std::string &  str)
static

Creates a new knot from either alphabetical or numerical Dowker-Thistlethwaite notation.

For an n-crossing knot, the input may be in one of two forms:

  • numerical Dowker-Thistlethwaite notation, which is a sequence of n even signed integers as described (amongst other places) in Section 2.2 of C. C. Adams, "The knot book", W. H. Freeman & Co., 1994;
  • alphabetical Dowker-Thistlethwaite notation, which transforms the numerical notation into a sequence of letters by replacing positive integers (2,4,6,...) with lower-case letters (a,b,c,...), and replacing negative integers (-2,-4,-6,...) with upper-case letters (A,B,C,...). This alphabetical variant can only be used to describe knots with 26 crossings or fewer.

Dowker-Thistlethwaite notation essentially describes the 4-valent graph of a knot but not the particular embedding in the plane. As a result, there can be ambiguity in the orientation of the diagram, and (for composite knots) even the topology of the knot itself. Furthermore, parsing Dowker-Thistlethwaite notation is complex since it requires an embedding to be deduced using some variant of a planarity testing algorithm. These issues are resolved using oriented Gauss codes, as used by the routines orientedGauss() and fromOrientedGauss().

As an example, you can construct the trefoil using either of the following variants of Dowker-Thistlethwaite notation:

4 6 2
bca

There are two variants of this routine. This variant takes a single string, which is either the alphabetical notation (in which any whitespace within the string will be ignored), or the numerical notation where the integers have been combined together and separated by whitespace. The other variant of this routine is only for the numerical variant, and it takes a sequence of integers defined by a pair of iterators.

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

Warning
In general, Dowker-Thistlethwaite notation does not contain enough information to uniquely reconstruct a knot. For prime knots, both a knot and its reflection can be described by the same notation; for composite knots, the same notation can describe knots that are topologically inequivalent, even when allowing for reflection. If you need to reconstruct a knot uniquely, consider using the oriented Gauss code instead.
While this routine does some error checking on the input, it does not test for planarity of the diagram. That is, if the input describes a knot diagram that must be drawn on some higher-genus surface as opposed to the plane, this will not be detected. Of course such inputs are not allowed, and it is currently up to the user to enforce this.
Author
Much of the code for this routine is based on the Dowker-Thistlethwaite implementation in the SnapPea/SnapPy kernel.
Parameters
streither the alphabetical or numerical Dowker-Thistlethwaite notation for a knot, as described above.
Returns
a newly constructed link, or null if the input was found to be invalid.

◆ fromDT() [2/2]

template<typename Iterator >
static Link* regina::Link::fromDT ( Iterator  begin,
Iterator  end 
)
static


Creates a new knot from an integer sequence using the numerical variant of Dowker-Thistlethwaite notation.

For an n-crossing knot, this must be a sequence of n even signed integers as described (amongst other places) in Section 2.2 of C. C. Adams, "The knot book", W. H. Freeman & Co., 1994.

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

Regina can also reconstruct a knot from alphabetical Dowker-Thistlethwaite notation, but for this you must use the other version of this routine that takes a single string argument.

For numerical Dowker-Thistlethwaite notation, there are two variants of this routine that you can use. The other variant (fromDT(const std::string&), which offers more detailed documentation) takes a single string, where the integers have been combined together and separated by whitespace. This variant takes a sequence of integers, defined by a pair of iterators.

Precondition
Iterator is a random access iterator type, and dereferencing such an iterator produces an integer.
Warning
In general, Dowker-Thistlethwaite notation does not contain enough information to uniquely reconstruct a knot. For prime knots, both a knot and its reflection can be described by the same notation; for composite knots, the same notation can describe knots that are topologically inequivalent, even when allowing for reflection. If you need to reconstruct a knot uniquely, consider using the oriented Gauss code instead.
While this routine does some error checking on the input, it does not test for planarity of the diagram. That is, if the input describes a knot diagram that must be drawn on some higher-genus surface as opposed to the plane, this will not be detected. Of course such 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 integers.
Author
Much of the code for this routine is based on the Dowker-Thistlethwaite implementation in the SnapPea/SnapPy kernel.
Parameters
beginan iterator that points to the beginning of the sequence of integers for the Dowker-Thistlethwaite notation for a knot.
endan iterator that points past the end of the sequence of integers for the Dowker-Thistlethwaite notation for a knot.
Returns
a newly constructed link, or null if the input was found to be invalid.

◆ fromGauss() [1/2]

static Link* regina::Link::fromGauss ( const std::string &  str)
static

Creates a new knot from a classical Gauss code.

Classical Gauss codes essentially describe the 4-valent graph of a knot but not the particular embedding in the plane. As a result, there can be ambiguity in the orientation of the diagram, and (for composite knots) even the topology of the knot itself. Furthermore, parsing a Gauss code is complex since it requires an embedding to be deduced using some variant of a planarity testing algorithm. These issues are resolved using oriented Gauss codes, as used by the routines orientedGauss() and fromOrientedGauss().

The Gauss code for an n-crossing knot is described by a sequence of 2n positive and negative integers, representing strands that pass over and under crossings respectively. Regina's implementation of Gauss codes comes with the following restrictions:

  • It can only be used for knots (i.e., links with exactly one component).
  • The crossings of the knot must be labelled 1, 2, ..., n (i.e., they cannot have be arbitrary natural numbers).

The format works as follows:

  • Label the crossings arbitrarily as 1, 2, ..., n.
  • Start at some point on the knot and follow it around. Whenever you pass crossing k, write the integer k if you pass over the crossing, or -k if you pass under the crossing.

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

As an example, you can construct the trefoil using the code:

1 -2 3 -1 2 -3

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

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

Warning
In general, the classical Gauss code does not contain enough information to uniquely reconstruct a knot. For prime knots, both a knot and its reflection can be described by the same Gauss code; for composite knots, the same Gauss code can describe knots that are topologically inequivalent, even when allowing for reflection. If you need to reconstruct a knot uniquely, consider using the oriented Gauss code instead.
While this routine does some error checking on the input, it does not test for planarity of the diagram. That is, if the input describes a knot diagram that must be drawn on some higher-genus surface as opposed to the plane, this will not be detected. Of course such inputs are not allowed, and it is currently up to the user to enforce this.
Author
Adam Gowty
Parameters
stra classical Gauss code for a knot, as described above.
Returns
a newly constructed link, or null if the input was found to be invalid.

◆ fromGauss() [2/2]

template<typename Iterator >
static Link* regina::Link::fromGauss ( Iterator  begin,
Iterator  end 
)
static


Creates a new knot from a classical Gauss code.

See fromGauss(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 (fromGauss(const std::string&), which offers more detailed documentation) takes a single string, where the integers have been combined together and separated by whitespace. This variant takes a sequence of integers, defined by a pair of iterators.

Precondition
Iterator is a random access iterator type, and dereferencing such an iterator produces an integer.
Warning
In general, the classical Gauss code does not contain enough information to uniquely reconstruct a knot. For prime knots, both a knot and its reflection can be described by the same Gauss code; for composite knots, the same Gauss code can describe knots that are topologically inequivalent, even when allowing for reflection. If you need to reconstruct a knot uniquely, consider using the oriented Gauss code instead.
While this routine does some error checking on the input, it does not test for planarity of the diagram. That is, if the input describes a knot diagram that must be drawn on some higher-genus surface as opposed to the plane, this will not be detected. Of course such 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 integers.
Author
Adam Gowty
Parameters
beginan iterator that points to the beginning of the sequence of integers for a classical Gauss code.
endan iterator that points past the end of the sequence of integers for a classical Gauss code.
Returns
a newly constructed link, or null if the input was found to be invalid.

◆ fromJenkins() [1/2]

static Link* regina::Link::fromJenkins ( const std::string &  str)
static

Builds a link from the text representation described by Bob Jenkins.

Jenkins uses this representation in his HOMFLY polynomial software, which is available online from http://burtleburtle.net/bob/knot/homfly.html.

In this format, a link is described by a sequence of integers separated by whitespace - the exact form of the whitespace does not matter, and additional whitespace at the beginning or end of this sequence is also allowed.

We assume that there are n crossings in the link, labelled arbitrarily as 0, 1, ..., n-1. The sequence of integers must contain, in order:

  • the number of components in the link;
  • for each link component:
    • the number of times you pass a crossing when traversing the component (i.e., the length of the component);
    • two integers for each crossing that you pass in such a traversal: the crossing label, and then either +1 or -1 according to whether you pass over or under the crossing respectively;
  • for each crossing:
    • the crossing label;
    • the sign of the crossing (either +1 or -1).

As an example, you could construct the left-hand trefoil using the following sequence:

1
6   0 1   1 -1   2 1   0 -1   1 1   2 -1
0 -1   1 -1   2 -1

Another example is the Hopf link, which you could construct using the following sequence:

2
2   0 1   1 -1
2   0 -1   1 1
0 1   1 1

The topology of the knot is defined precisely by this data, but the precise embedding of the diagram in the plane remains ambiguous. To be exact: the embedding of the diagram in the 2-sphere is defined precisely, but there remains a choice of which 2-cell of this embedding will contain the point at infinity (i.e., which 2-cell becomes the exterior cell of the diagram in the plane).

There are two variants of this routine. This variant takes a single string containing the integer sequence. The other variant takes an input stream, from which the sequence of integers will be read.

Warning
While this routine does some error checking on the input, it does not test for planarity of the diagram. That is, if the input describes a knot diagram that must be drawn on some higher-genus surface as opposed to the plane, this will not be detected. Of course such inputs are not allowed, and it is currently up to the user to enforce this.
Note
You can export an existing link in Jenkins' format by calling the routine jenkins().
Parameters
stra string containing a sequence of integers separated by whitespace that describes a link, as detailed above.
Returns
a newly constructed link, or null if the input was found to be invalid.

◆ fromJenkins() [2/2]

static Link* regina::Link::fromJenkins ( std::istream &  in)
static


Builds a link from the text representation described by Bob Jenkins.

Jenkins uses this representation in his HOMFLY polynomial software, which is available online from http://burtleburtle.net/bob/knot/homfly.html.

See fromJenkins(const std::string&) for a detailed description of this format.

There are two variants of this routine. The other variant takes a single string containing the integer sequence. This variant takes an input stream, from which the sequence of integers will be read.

In this variant, this routine reads the integers that describe the link and then leaves the remainder of the input stream untouched (in particular, the stream may contain additional material, which can be read by the user after this routine has finished).

Warning
While this routine does some error checking on the input, it does not test for planarity of the diagram. That is, if the input describes a knot diagram that must be drawn on some higher-genus surface as opposed to the plane, this will not be detected. Of course such inputs are not allowed, and it is currently up to the user to enforce this.
Python
Not present.
Parameters
inan input stream that begins with a sequence of integers separated by whitespace that describes a link.
Returns
a newly constructed link, or null if the input was found to be invalid.

◆ fromKnotSig()

static Link* regina::Link::fromKnotSig ( const std::string &  sig)
static

Recovers a knot diagram from its signature.

See knotSig() for more information on knot signatures.

The knot that is returned will be newly created, and it is the responsibility of the caller of this routine to destroy it.

Calling knotSig() followed by fromKnotSig() is not guaranteed to produce an identical knot diagram to the original, but it is guaranteed to produce one that is related by relabelling, rotation, and optionally (according to the arguments that were passed to knotSig()) reflection and/or reversal.

Parameters
sigthe signature of the knot diagram to construct. Note that signatures are case-sensitive.
Returns
a newly allocated knot if the reconstruction was successful, or null if the given string was not a valid knot signature.

◆ fromOrientedGauss() [1/2]

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

Creates a new knot from an "oriented" variant of the Gauss code.

Classical Gauss codes essentially describe the 4-valent graph of a knot but not the particular embedding in the plane. As a result, there can be ambiguity in the orientation of the diagram, and (for composite knots) even the topology of the knot itself. Furthermore, parsing a Gauss code is complex since it requires an embedding to be deduced using some variant of a planarity testing algorithm.

Andreeva et al. describe a variant of the Gauss code that includes extra information about the embedding, so as to remove both the ambiguity and the complexity in the conversion procedure. With this extra information, the knot and its orientation are well-defined (but the diagram is still ambiguous - see the note below).

This "oriented" format is described at http://www.javaview.de/services/knots/doc/description.html#gc. Regina adds two additional restrictions on this format:

  • It can only be used for knots (i.e., links with exactly one component).
  • The crossings of the knot must be labelled 1, 2, ..., n (i.e., they cannot have be arbitrary natural numbers).

The format works as follows:

  • Label the crossings arbitrarily as 1, 2, ..., n.
  • Start at some point on the knot and follow it around. 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.

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

As an example, you can construct the left-hand trefoil using the following code:

+>1 -<2 +>3 -<1 +>2 -<3

The topology of the knot is defined precisely by this data, but the precise embedding of the diagram in the plane remains ambiguous. To be exact: the embedding of the diagram in the 2-sphere is defined precisely, but there remains a choice of which 2-cell of this embedding will contain the point at infinity (i.e., which 2-cell becomes the exterior cell of the diagram in the plane).

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 planarity of the diagram. That is, if the input describes a knot diagram that must be drawn on some higher-genus surface as opposed to the plane, this will not be detected. Of course such inputs are not allowed, and it is currently up to the user to enforce this.
Parameters
stran "oriented" Gauss code for a knot, as described above.
Returns
a newly constructed link, or null if the input was found to be invalid.

◆ fromOrientedGauss() [2/2]

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


Creates a new knot from an "oriented" variant of the Gauss code.

This format is described by Andreeva et al. at http://www.javaview.de/services/knots/doc/description.html#gc, though Regina limits its use to knots (i.e., one-component links), and insists that the crossings be numbered 1, ..., n (not arbitrary natural numbers).

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 planarity of the diagram. That is, if the input describes a knot diagram that must be drawn on some higher-genus surface as opposed to the plane, this will not be detected. Of course such 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 link, or null if the input was found to be invalid.

◆ gauss() [1/2]

std::string regina::Link::gauss ( ) const

Outputs a classical Gauss code for this knot.

In general, the classical Gauss code does not carry enough information to uniquely reconstruct the knot. For instance, both a knot and its reflection can be described by the same Gauss code; moreover, for composite knots, the Gauss code can describe inequivalent knots (even when allowing for reflections). If you need a code that specifies the knot uniquely, consider using the oriented Gauss code instead.

Currently Regina only supports Gauss codes for knots, not multiple-component links. If this link does not have precisely one component then the empty string will be returned.

The string 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
a classical Gauss code for this knot, or the empty string if this is a link with zero or multiple components.

◆ gauss() [2/2]

void regina::Link::gauss ( std::ostream &  out) const


Writes a classical Gauss code for this knot to the given output stream.

In general, the classical Gauss code does not carry enough information to uniquely reconstruct the knot. For instance, both a knot and its reflection can be described by the same Gauss code; moreover, for composite knots, the Gauss code can describe inequivalent knots (even when allowing for reflections). If you need a code that specifies the knot uniquely, consider using the oriented Gauss code instead.

Currently Regina only supports Gauss codes for knots, not multiple-component links. If this link does not have precisely one component then nothing will be output at all.

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 gauss(), which takes no arguments and returns the output as a string.
Parameters
outthe output stream to which to write.

◆ hasReducingPass()

bool regina::Link::hasReducingPass ( ) const

Tests whether this knot has a pass move that will reduce the number of crossings.

Currently this routine is only available for knots, not multiple-component links.

A pass move involves taking a section of the knot that involves only over-crossings (or only under-crossings), and then lifting that section above (or beneath respectively) the diagram and placing it back again in a different location. In particular, this routine searches for a different location that will involve fewer crossings than the original location.

This routine does not actually perform the pass move; it simply determines whether one exists.

The running time is cubic in the number of crossings.

Precondition
This link is actually a knot (i.e., it contains exactly one component).
Returns
true if and only if there is a pass move that reduces the number of crossings.

◆ hasSafePtr()

bool regina::SafePointeeBase< Packet >::hasSafePtr ( ) const
inlineinherited

Is there one or more SafePtr currently pointing to this object?

◆ homfly()

const Laurent2< Integer > & regina::Link::homfly ( Algorithm  alg = ALG_DEFAULT,
ProgressTracker tracker = nullptr 
) const
inline

Returns the HOMFLY polynomial of this link, as a polynomial in alpha and z.

This routine is simply an alias for homflyAZ(). See the documentation for homflyAZ() for further details.

To pretty-print this polynomial for human consumption, you can call Laurent2::str(Link::homflyVarX, Link::homflyVarY).

Bear in mind that each time the link changes, all of its polynomials will be deleted. Thus the reference that is returned from this routine should not be kept for later use. Instead, homfly() should be called again; this will be instantaneous if the HOMFLY polynomial has already been calculated.

Parameters
algthe algorithm with which to compute the polynomial. If you are not sure, the default (ALG_DEFAULT) is a safe choice. If you wish to specify a particular algorithm, there are currently two choices: ALG_BACKTRACK will use Kauffman's skein-template algorithm, and ALG_TREEWIDTH will use a fixed-parameter tractable treewidth-based algorithm.
trackera progress tracker through which progress will be reported, or null if no progress reporting is required.
Returns
the HOMFLY polynomial. If a progress tracker was passed then this return value must be ignored, and you should call homfly() again once the tracker is marked as finished.

◆ homflyAZ()

const Laurent2<Integer>& regina::Link::homflyAZ ( Algorithm  alg = ALG_DEFAULT,
ProgressTracker tracker = nullptr 
) const

Returns the HOMFLY polynomial of this link, as a polynomial in alpha and z.

This variant of the HOMFLY polynomial is described (amongst other places) in G. Gouesbet et al., "Computer evaluation of Homfly polynomials by using Gauss codes, with a skein-template algorithm", Applied Mathematics and Computation 105 (1999), 271-289.

The (alpha, z) and (l, m) variants of the HOMFLY polynomial are related by a simple transformation: alpha = l i and z = -m i, where i represents (as usual) a square root of -1.

This routine returns a Laurent polynomial in the two variables alpha and z (which are represented by x and y respectively in the class Laurent2).

If this is the empty link, then this routine will return the zero polynomial.

To pretty-print this polynomial for human consumption, you can call Laurent2::str(Link::homflyAZVarX, Link::homflyAZVarY).

The default implementation uses Kauffman's skein-template algorithm; see L. H. Kauffman, "State models for link polynomials", L'enseignement mathematique 36 (1990), 1-37, or for a more recent summary see G. Gouesbet et al., "Computer evaluation of Homfly polynomials by using Gauss codes, with a skein-template algorithm", Applied Mathematics and Computation 105 (1999), 271-289.

Bear in mind that each time the link changes, all of its polynomials will be deleted. Thus the reference that is returned from this routine should not be kept for later use. Instead, homflyAZ() should be called again; this will be instantaneous if the HOMFLY polynomial has already been calculated.

If the HOMFLY polynomial has already been computed, then the result will be cached and so this routine will be very fast (since it just returns the previously computed result). Otherwise the computation could be quite slow, particularly for larger numbers of crossings. This (potentially) long computation can be managed by passing a progress tracker:

  • If a progress tracker is passed and the polynomial has not yet been computed, then the calculation will take place in a new thread and this routine will return immediately. Once the progress tracker indicates that the calculation has finished, you can call homflyAZ() again to retrieve the polynomial.
  • If no progress tracker is passed and the polynomial has not yet been computed, the calculation will run in the current thread and this routine will not return until it is complete.
  • If the HOMFLY polynomial has already been computed (either in terms of alpha and z or in terms of l and m), then this routine will return immediately with the pre-computed value. If a progress tracker is passed then it will be marked as finished.
Parameters
algthe algorithm with which to compute the polynomial. If you are not sure, the default (ALG_DEFAULT) is a safe choice. If you wish to specify a particular algorithm, there are currently two choices: ALG_BACKTRACK will use Kauffman's skein-template algorithm, and ALG_TREEWIDTH will use a fixed-parameter tractable treewidth-based algorithm.
trackera progress tracker through which progress will be reported, or null if no progress reporting is required.
Returns
the HOMFLY polynomial. If a progress tracker was passed then this return value must be ignored, and you should call homflyAZ() again once the tracker is marked as finished.

◆ homflyLM()

const Laurent2<Integer>& regina::Link::homflyLM ( Algorithm  alg = ALG_DEFAULT,
ProgressTracker tracker = nullptr 
) const

Returns the HOMFLY polynomial of this link, as a polynomial in l and m.

This variant of the HOMFLY polynomial is described (amongst other places) in C. C. Adams, "The knot book", W. H. Freeman & Co., 1994.

The (alpha, z) and (l, m) variants of the HOMFLY polynomial are related by a simple transformation: alpha = l i and z = -m i, where i represents (as usual) a square root of -1.

This routine returns a Laurent polynomial in the two variables l and m (which are represented by x and y respectively in the class Laurent2).

If this is the empty link, then this routine will return the zero polynomial.

To pretty-print this polynomial for human consumption, you can call Laurent2::str(Link::homflyLMVarX, Link::homflyLMVarY).

The default implementation uses Kauffman's skein-template algorithm; see L. H. Kauffman, "State models for link polynomials", L'enseignement mathematique 36 (1990), 1-37, or for a more recent summary see G. Gouesbet et al., "Computer evaluation of Homfly polynomials by using Gauss codes, with a skein-template algorithm", Applied Mathematics and Computation 105 (1999), 271-289.

Bear in mind that each time the link changes, all of its polynomials will be deleted. Thus the reference that is returned from this routine should not be kept for later use. Instead, homflyLM() should be called again; this will be instantaneous if the HOMFLY polynomial has already been calculated.

If the HOMFLY polynomial has already been computed, then the result will be cached and so this routine will be very fast (since it just returns the previously computed result). Otherwise the computation could be quite slow, particularly for larger numbers of crossings. This (potentially) long computation can be managed by passing a progress tracker:

  • If a progress tracker is passed and the polynomial has not yet been computed, then the calculation will take place in a new thread and this routine will return immediately. Once the progress tracker indicates that the calculation has finished, you can call homflyLM() again to retrieve the polynomial.
  • If no progress tracker is passed and the polynomial has not yet been computed, the calculation will run in the current thread and this routine will not return until it is complete.
  • If the HOMFLY polynomial has already been computed (either in terms of alpha and z or in terms of l and m), then this routine will return immediately with the pre-computed value. If a progress tracker is passed then it will be marked as finished.
Parameters
algthe algorithm with which to compute the polynomial. If you are not sure, the default (ALG_DEFAULT) is a safe choice. If you wish to specify a particular algorithm, there are currently two choices: ALG_BACKTRACK will use Kauffman's skein-template algorithm, and ALG_TREEWIDTH will use a fixed-parameter tractable treewidth-based algorithm.
trackera progress tracker through which progress will be reported, or null if no progress reporting is required.
Returns
the HOMFLY polynomial. If a progress tracker was passed then this return value must be ignored, and you should call homflyLM() again once the tracker is marked as finished.

◆ insertTorusLink()

void regina::Link::insertTorusLink ( int  p,
int  q,
bool  positive = true 
)

Inserts a new (p, q) torus link into this link.

The parameters p and q must be non-negative, but they do not need to be coprime.

All of the crossings in the new torus link component(s) will be positive if the argument positive is true, or negative otherwise.

The new crossings and components will be inserted at the end of the respective lists in this link.

If your aim is to create a new torus link (as opposed to inserting one into an existing link), it is simpler to just call ExampleLink::torus().

Parameters
pthe first parameter of the new torus link; this must be non-negative.
qthe second parameter of the new torus link; this must also be non-negative.
positivetrue if the crossings in the new torus link should be positive, or false if they should be negative.

◆ intelligentSimplify()

bool regina::Link::intelligentSimplify ( )

Attempts to simplify the link diagram using fast and greedy heuristics.

Specifically, this routine tries combinations of Reidemeister moves with the aim of reducing the number of crossings.

Currently this routine uses simplifyToLocalMinimum() in combination with random type III Reidemeister moves.

Although intelligentSimplify() often works well, it can sometimes get stuck. If this link is a knot (i.e., it has precisely one component), then in such cases you can try the more powerful but (much) slower simplifyExhaustive() instead.

This routine will never reflect or reverse the link.

Warning
Running this routine multiple times upon the same link may return different results, since the implementation makes random decisions. More broadly, the implementation of this routine (and therefore its results) may change between different releases of Regina.

◆ internalClonePacket()

Packet * regina::Link::internalClonePacket ( Packet parent) const
inlineoverrideprotectedvirtual

Makes a newly allocated copy of this packet.

This routine should not insert the new packet into the tree structure, clone the packet's associated tags or give the packet a label. It should also not clone any descendants of this packet.

You may assume that the new packet will eventually be inserted into the tree beneath either the same parent as this packet or a clone of that parent.

Parameters
parentthe parent beneath which the new packet will eventually be inserted.
Returns
the newly allocated packet.

Implements regina::Packet.

◆ isAlternating()

bool regina::Link::isAlternating ( ) const

Returns whether this knot diagram is alternating.

Note that this routine cannot tell whether the knot is alternating (i.e., whether there exists an alternating diagram). Instead, it simply returns whether this specific diagram is alternating or not.

The empty diagram and any zero-crossing unknot components will be considered alternating.

Returns
true if this is an alternating diagram, or false if this is a non-alternating diagram.

◆ isEmpty()

bool regina::Link::isEmpty ( ) const
inline

Determines whether this link is empty.

An empty link is one with no components at all.

Returns
true if and only if this link is empty.

◆ jenkins() [1/2]

std::string regina::Link::jenkins ( ) const

Exports this link as a string using the text representation described by Bob Jenkins.

Jenkins uses this representation in his HOMFLY polynomial software, which is available online from http://burtleburtle.net/bob/knot/homfly.html.

Jenkins' text format uses a sequence of integers separated by whitespace. For details of this format, see the documentation for fromJenkins(const std::string&), which imports links in this format.

The string will contain multiple lines, and will end in a newline.

Note
There is another variant of this routine that, instead of returning a string, writes directly to an output stream.
Returns
a description of this link using Jenkins' text format.

◆ jenkins() [2/2]

void regina::Link::jenkins ( std::ostream &  out) const


Exports this link to the given output stream using the text representation described by Bob Jenkins.

Jenkins uses this representation in his HOMFLY polynomial software, which is available online from http://burtleburtle.net/bob/knot/homfly.html.

Jenkins' text format uses a sequence of integers separated by whitespace. For details of this format, see the documentation from fromJenkins(), which imports links using this format.

The output will contain multiple lines, and will end in a newline.

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 jenkins(), which takes no arguments and returns the output as a string.
Parameters
outthe output stream to which to write.

◆ jones()

const Laurent<Integer>& regina::Link::jones ( Algorithm  alg = ALG_DEFAULT,
ProgressTracker tracker = nullptr 
) const

Returns the Jones polynomial of this link, but with all exponents doubled.

By "all exponents doubled", we are indicating that the Jones polynomial is in fact a Laurent polynomial in the square root of t. So, for example:

  • The right-hand trefoil has Jones polynomial 1/t + 1/t^3 - 1/t^4, and so this routine returns the Laurent polynomial x^-2 + x^-6 - x^-8.
  • The Hopf link has Jones polynomial -1/sqrt(x) - 1/sqrt(x^5), and so this routine returns the Laurent polynomial -x^-1 - x^-5.

If this is the empty link, then this routine will return the zero polynomial.

Regina follows the conventions described in C. C. Adams, "The knot book", W. H. Freeman & Co., 1994. If you wish to convert to the conventions used by Khovanov as described in Dror Bar-Natan, "On Khovanov's categorifiction of the Jones polynomial", Algebraic & Geometric Topology 2 (2002), 337-370, you can simply take the polynomial returned by this routine and replace the variable x (which represents the square root of t) with the expression -q.

To pretty-print this polynomial for human consumption, you can call Laurent::str(Link::jonesVar).

Bear in mind that each time the link changes, all of its polynomials will be deleted. Thus the reference that is returned from this routine should not be kept for later use. Instead, jones() should be called again; this will be instantaneous if the Jones polynomial has already been calculated.

If this polynomial has already been computed, then the result will be cached and so this routine will be very fast (since it just returns the previously computed result). Otherwise the computation could be quite slow, particularly for larger numbers of crossings. This (potentially) long computation can be managed by passing a progress tracker:

  • If a progress tracker is passed and the polynomial has not yet been computed, then the calculation will take place in a new thread and this routine will return immediately. Once the progress tracker indicates that the calculation has finished, you can call bracket() again to retrieve the polynomial.
  • If no progress tracker is passed and the polynomial has not yet been computed, the calculation will run in the current thread and this routine will not return until it is complete.
  • If the requested invariant has already been computed, then this routine will return immediately with the pre-computed value. If a progress tracker is passed then it will be marked as finished.
Warning
The naive algorithm can only handle a limited number of crossings (currently less than the number of bits in a long, which on a typical machine is 64). If you pass ALG_NAIVE and you have too many crossings (which is not advised, since the naive algorithm requires 2^n time), then this routine will ignore your choice of algorithm and use the treewidth-based algorithm regardless.
Parameters
algthe algorithm with which to compute the polynomial. If you are not sure, the default (ALG_DEFAULT) is a safe choice. If you wish to specify a particular algorithm, there are currently two choices: ALG_NAIVE is a slow algorithm that computes the Kauffman bracket by resolving all crossings in all possible ways, and ALG_TREEWIDTH uses a fixed-parameter tractable treewidth-based algorithm.
trackera progress tracker through which progress will be reported, or null if no progress reporting is required.
Returns
the Jones polynomial. If a progress tracker was passed then this return value must be ignored, and you should call jones() again once the tracker is marked as finished.

◆ knotSig()

std::string regina::Link::knotSig ( bool  useReflection = true,
bool  useReversal = true 
) const

Constructs the signature for this knot diagram.

A signature is a compact text representation of a knot diagram that unique determines the knot up to relabelling, rotation, and (optionally) reflection and/or reversal.

Currently signatures are only implemented for knots, not empty or multiple component links. If this link does not have precisely one component, then this routine will return the empty string.

The signature is constructed entirely of printable characters, and has length proportional to n log n, where n is the number of crossings.

The routine fromKnotSig() can be used to recover a knot from its signature. The resulting knot might not be identical to the original, but it will be related by zero or more applications of relabelling, rotation, and/or (according to the arguments) reflection and reversal.

This routine runs in quadratic time.

Parameters
useReflectiontrue if the reflection of a knot diagram should have the same signature as the original, or false if these should be distinct (assuming the diagram is not symmetric under reflection).
useReversaltrue if the reversal of a knot diagram should have the same signature as the original, or false if these should be distinct (assuming the diagram is not symmetric under reversal).
Returns
the signature for this knot diagram.

◆ knowsBracket()

bool regina::Link::knowsBracket ( ) const
inline

Is the Kauffman bracket polynomial of this link diagram already known? See bracket() for further details.

If this property is already known, future calls to bracket() will be very fast (simply returning the precalculated value).

Returns
true if and only if this property is already known.

◆ knowsHomfly()

bool regina::Link::knowsHomfly ( ) const
inline

Is the HOMFLY polynomial of this link diagram already known? See homflyAZ() and homflyLM() for further details.

If this property is already known, future calls to homfly(), homflyAZ() and homflyLM() will all be very fast (simply returning the precalculated values).

Returns
true if and only if this property is already known.

◆ knowsJones()

bool regina::Link::knowsJones ( ) const
inline

Is the Jones polynomial of this link diagram already known? See jones() for further details.

If this property is already known, future calls to jones() will be very fast (simply returning the precalculated value).

Returns
true if and only if this property is already known.

◆ linking()

long regina::Link::linking ( ) const

Returns the linking number of this link.

This is an invariant of the link, computed as half the sum of the signs of all crossings that involve different link components.

The algorithm to compute linking number is linear time.

Returns
the linking number.

◆ niceTreeDecomposition()

const TreeDecomposition & regina::Link::niceTreeDecomposition ( ) const
inline

Returns a nice tree decomposition of the planar 4-valent multigraph formed by this link diagram.

This can (for example) be used in implementing algorithms that are fixed-parameter tractable in the treewidth of this graph.

See TreeDecomposition for further details on tree decompositions, and see TreeDecomposition::makeNice() for details on what it means to be a nice tree decomposition.

This routine is fast: it will use a greedy algorithm to find a tree decomposition with (hopefully) small width, but with no guarantees that the width of this tree decomposition is the smallest possible.

The tree decomposition will be cached, so that if this routine is called a second time (and the underlying link has not been changed) then the same tree decomposition will be returned immediately.

If you wish to supply your own tree decomposition (as opposed to relying on the greedy heuristics that Regina implements), then you can supply it by calling useTreeDecomposition().

Returns
a nice tree decomposition of this link diagram.

◆ orientedGauss() [1/2]

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

Outputs an oriented Gauss code for this knot.

The oriented Gauss code, based on a format used by Andreeva et al., is an extension of the classical Gauss code with additional characters to describe the orientation of the other strand passing by at each crossing. For details of this format, see the documentation for fromOrientedGauss(const std::string&), which imports links in this format.

The key advantage of using the oriented Gauss code (as opposed to the classical Gauss code) is that an oriented Gauss code always describes a unique knot, and moreover (for knots that are not equivalent to their reflections) it describes a unique reflection of that knot.

Currently Regina only supports Gauss codes for knots, not multiple-component links. If this link does not have precisely one component then the empty string will be returned.

The string 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 knot, or the empty string if this is a link with zero or multiple components.

◆ orientedGauss() [2/2]

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


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

The oriented Gauss code, based on a format used by Andreeva et al., is an extension of the classical Gauss code with additional characters to describe the orientation of the other strand passing by at each crossing. For details of this format, see the documentation for fromOrientedGauss(const std::string&), which imports links in this format.

The key advantage of using the oriented Gauss code (as opposed to the classical Gauss code) is that an oriented Gauss code always describes a unique knot, and moreover (for knots that are not equivalent to their reflections) it describes a unique reflection of that knot.

Currently Regina only supports Gauss codes for knots, not multiple-component links. If this link does not have precisely one component then nothing will be output at all.

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.

◆ pace()

std::string regina::Link::pace ( ) const

Returns a text representation of the underlying planar 4-valent multigraph, using the PACE text format.

The text format is described in detail at https://pacechallenge.wordpress.com/pace-2016/track-a-treewidth/ , and is documented in detail by the routine writePACE().

This routine simply returns the output of writePACE() as a string, instead of writing it to an output stream.

See the writePACE() notes for further details.

Returns
the output of writePACE(), as outlined above.
See also
https://pacechallenge.wordpress.com/pace-2016/track-a-treewidth/

◆ parallel()

Link* regina::Link::parallel ( int  k,
Framing  framing = FRAMING_SEIFERT 
) const

Returns k cables of this link, all parallel to each other using the given framing.

This routine creates a new link by:

  • treating each component of this link as a ribbon, using the given framing;
  • creating k parallel copies of the original link, following each other side-by-side along these ribbons.

This link will not be modified.

The result will returned as a new link, and it is the responsibility of the caller of this routine to destroy it.

Parameters
kthe number of parallel copies to create. This must be non-negative.
framingthe framing under which these copies will be parallel.
Returns
k parallel copies of this link, as a newly-created object.

◆ r1() [1/2]

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

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

There are two boolean arguments that control the behaviour of this routine: check and perform.

  • If check and perform are both true (the default), then this routine will first check whether this move can be performed at the given location. If so, it will perform the move and return true. If not, it will do nothing and return false.
  • If check is true but perform is false, then this routine will simply check whether this move can be performed at the given location and return true or false accordingly.
  • If check is false but perform is true, then this routine will perform the move without any prior checks, and will always return true. In this case, it must be known in advance that the move can be performed at the given location.
  • If check and perform are both false, then this routine does nothing and just returns true. (There is no reason to use this combination of arguments.)

The location of this move is specified by the argument crossing, which indicates the crossing that will be removed. Specifically, this move involves undoing a trivial twist at the given crossing.

You may pass a null pointer for crossing. However, in this case the move cannot be performed, which means (i) check must be true, and therefore (ii) this routine will do nothing and return false.

Warning
A side-effect of this move is that, because one crossing is being removed, the other crossings in the link may be reindexed. However, no crossings other than the one involved in this move will be destroyed.
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 link.
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.

◆ r1() [2/2]

bool regina::Link::r1 ( StrandRef  arc,
int  side,
int  sign,
bool  check = true,
bool  perform = true 
)

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

There are two boolean arguments that control the behaviour of this routine: check and perform.

  • If check and perform are both true (the default), then this routine will first check whether this move can be performed at the given location. If so, it will perform the move and return true. If not, it will do nothing and return false.
  • If check is true but perform is false, then this routine will simply check whether this move can be performed at the given location and return true or false accordingly.
  • If check is false but perform is true, then this routine will perform the move without any prior checks, and will always return true. In this case, it must be known in advance that the move can be performed at the given location.
  • If check and perform are both false, then this routine does nothing and just returns true. (There is no reason to use this combination of arguments.)

The location of this move is specified by the argument arc. Specifically, this move involves adding a trivial twist to the given arc; the arguments side and sign indicate on which side of the arc and with which orientation the new twist will be made. See the StrandRef documentation for the convention on how arcs are represented using StrandRef objects.

If arc is a null reference, then the new twist will be added to a zero-crossing unknot component; it will be assumed that this unknot component is oriented clockwise. If arc is null but there is no zero-crossing component then the move cannot be performed, and if arc is null but there are multiple zero-crossing components then the first such component will be used.

This move is almost always able to be performed: the only situation in which it cannot be performed is if arc is a null reference but this link contains no zero-crossing components, as discussed above.

The existing crossings in this link will keep the same indices, and the new crossing will be given the next index that is available.

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 link.
Parameters
arcidentifies the arc of the link in which the new twist will be introduced, as described above.
side0 if the twist should be introduced on the left of the arc (when walking along the arc in the forward direction), or 1 if the twist should be introduced on the right of the arc.
signthe sign of the new crossing that will be introduced as part of the twist; this must be +1 or -1.
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/3]

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

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

There are two variants of this routine: one that takes an arc, and one that takes a crossing. This variant, which takes an arc, is more flexible (since either of the two arcs involved in this move can be passed). The other variant, which takes a crossing, offers a canonical way of performing the move (since for each move there is exactly one crossing that describes it).

There are two boolean arguments that control the behaviour of this routine: check and perform.

  • If check and perform are both true (the default), then this routine will first check whether this move can be performed at the given location. If so, it will perform the move and return true. If not, it will do nothing and return false.
  • If check is true but perform is false, then this routine will simply check whether this move can be performed at the given location and return true or false accordingly.
  • If check is false but perform is true, then this routine will perform the move without any prior checks, and will always return true. In this case, it must be known in advance that the move can be performed at the given location.
  • If check and perform are both false, then this routine does nothing and just returns true. (There is no reason to use this combination of arguments.)

The location of this move is specified by the argument arc. Specifically, this move involves pulling apart two arcs of the link that surround a bigon; the given arc must be one of these two arcs. See the StrandRef documentation for the convention on how arcs are represented using StrandRef objects.

You may pass a null reference for arc. However, in this case the move cannot be performed, which means (i) check must be true, and therefore (ii) this routine will do nothing and return false.

Warning
A side-effect of this move is that, because two crossings are being removed, the other crossings in the link may be reindexed. However, no crossings other than the two involved in this move will be destroyed.
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 link.
Parameters
arcidentifies one of the arcs of the bigon about which the move will be performed, as described above.
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/3]

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

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

There are two variants of this routine: one that takes an arc, and one that takes a crossing. The other variant, which takes an arc, is more flexible (since either of the two arcs involved in this move can be passed). This variant, which takes a crossing, offers a canonical way of performing the move (since for each move there is exactly one crossing that describes it).

There are two boolean arguments that control the behaviour of this routine: check and perform.

  • If check and perform are both true (the default), then this routine will first check whether this move can be performed at the given location. If so, it will perform the move and return true. If not, it will do nothing and return false.
  • If check is true but perform is false, then this routine will simply check whether this move can be performed at the given location and return true or false accordingly.
  • If check is false but perform is true, then this routine will perform the move without any prior checks, and will always return true. In this case, it must be known in advance that the move can be performed at the given location.
  • If check and perform are both false, then this routine does nothing and just returns true. (There is no reason to use this combination of arguments.)

The location of this move is specified by the argument crossing, Specifically, this move involves pulling apart two arcs of the link (one upper, one lower) that both run between the same pair of crossings. The given crossing should be the start point of the upper arc; that is, when following the upper arc forwards, crossing should be the first of the two crossings that we encounter. Note that crossing is one of the two crossings that will be removed by this move.

You may pass a null pointer for crossing. However, in this case the move cannot be performed, which means (i) check must be true, and therefore (ii) this routine will do nothing and return false.

Warning
A side-effect of this move is that, because two crossings are being removed, the other crossings in the link may be reindexed. However, no crossings other than the two involved in this move will be destroyed.
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 link.
Parameters
crossingidentifies the crossing at the beginning of the "upper" arc that features in this move, as described above.
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() [3/3]

bool regina::Link::r2 ( StrandRef  upperArc,
int  upperSide,
StrandRef  lowerArc,
int  lowerSide,
bool  check = true,
bool  perform = true 
)

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

There are two boolean arguments that control the behaviour of this routine: check and perform.

  • If check and perform are both true (the default), then this routine will first check whether this move can be performed at the given location. If so, it will perform the move and return true. If not, it will do nothing and return false.
  • If check is true but perform is false, then this routine will simply check whether this move can be performed at the given location and return true or false accordingly.
  • If check is false but perform is true, then this routine will perform the move without any prior checks, and will always return true. In this case, it must be known in advance that the move can be performed at the given location.
  • If check and perform are both false, then this routine does nothing and just returns true. (There is no reason to use this combination of arguments.)

The location of this move is specified by the arguments upperArc, upperSide, lowerArc and lowerSide. Specifically, this move involves taking the arc upperArc and pushing it over lowerArc so that the two arcs overlap. The arguments upperSide and lowerSide indicate on which side of each arc the overlap takes place. See the StrandRef documentation for the convention on how arcs are represented using StrandRef objects.

If either upperArc or lowerArc is a null reference, then the move will be performed upon a zero-crossing unknot component; it will be assumed that this unknot component is oriented clockwise. If one of these arguments is a null reference but there is no zero-crossing component then the move cannot be performed, and if there are multiple zero-crossing components then the first such component will be used.

Likewise, if both arcs are null references, then the move will be performed upon two different zero-crossing unknot components. In this case, if there are fewer than two such components then the move cannot be performed, and otherwise upperArc will be the first such component and lowerArc will be the second.

Currently, Regina cannot perform the move when upperArc and lowerArc represent the same arc (or the same zero-crossing unknot component). In this case there is a workaround: you can achieve the same effect by performing two type I Reidemeister moves (i.e., by adding two twists).

The existing crossings in this link will keep the same indices, and the two new crossings will be given the next two indices that are available.

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.
Each of the given strand references is either a null reference, or else refers to some strand of some crossing in this link.
Warning
The check for this move is expensive (linear time), since it includes testing whether both sides-of-arcs belong to the same 2-cell of the knot diagram.
Parameters
upperArcidentifies the arc of the link which will be passed over the other, as described above.
upperSide0 if the new overlap should take place on the left of upperArc (when walking along upperArc in the forward direction), or 1 if the new overlap should take place on the right of upperArc.
lowerArcidentifies the arc of the link which will be passed beneath the other, as described above.
lowerSide0 if the new overlap should take place on the left of lowerArc (when walking along lowerArc in the forward direction), or 1 if the new overlap should take place on the right of lowerArc.
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.

◆ r3() [1/2]

bool regina::Link::r3 ( StrandRef  arc,
int  side,
bool  check = true,
bool  perform = true 
)

Tests for and/or performs a type III Reidemeister move.

There are two variants of this routine: one that takes an arc, and one that takes a crossing. This variant, which takes an arc, is more flexible (since any of the three arcs involved in this move can be passed). The other variant, which takes a crossing, offers a canonical way of performing the move (since for each move there is exactly one crossing that describes it).

There are two boolean arguments that control the behaviour of this routine: check and perform.

  • If check and perform are both true (the default), then this routine will first check whether this move can be performed at the given location. If so, it will perform the move and return true. If not, it will do nothing and return false.
  • If check is true but perform is false, then this routine will simply check whether this move can be performed at the given location and return true or false accordingly.
  • If check is false but perform is true, then this routine will perform the move without any prior checks, and will always return true. In this case, it must be known in advance that the move can be performed at the given location.
  • If check and perform are both false, then this routine does nothing and just returns true. (There is no reason to use this combination of arguments.)

The location of this move is specified by the arguments arc and side. Specifically, this move takes place around a triangle; the given arc must form one of the three edges of this triangle. The argument side indicates on which side of the arc the third crossing is located. See the StrandRef documentation for the convention on how arcs are represented using StrandRef objects.

You may pass a null reference for arc. However, in this case the move cannot be performed, which means (i) check must be true, and therefore (ii) this routine will do nothing and return false.

All crossings in this link will keep the same indices, and no crossings will be created or destroyed. Instead, the three crossings involved in this move will simply be reordered along the various segments of the link.

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 link.
Parameters
arcidentifies one of the arcs of the triangle about which the move will be performed, as described above.
side0 if the third crossing of the triangle is located to the left of the arc (when walking along the arc in the forward direction), or 1 if the third crossing is located on the right of the arc.
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.

◆ r3() [2/2]

bool regina::Link::r3 ( Crossing crossing,
int  side,
bool  check = true,
bool  perform = true 
)
inline

Tests for and/or performs a type III Reidemeister move.

There are two variants of this routine: one that takes an arc, and one that takes a crossing. The other variant, which takes an arc, is more flexible (since any of the three arcs involved in this move can be passed). This variant, which takes a crossing, offers a canonical way of performing the move (since for each move there is exactly one crossing that describes it).

There are two boolean arguments that control the behaviour of this routine: check and perform.

  • If check and perform are both true (the default), then this routine will first check whether this move can be performed at the given location. If so, it will perform the move and return true. If not, it will do nothing and return false.
  • If check is true but perform is false, then this routine will simply check whether this move can be performed at the given location and return true or false accordingly.
  • If check is false but perform is true, then this routine will perform the move without any prior checks, and will always return true. In this case, it must be known in advance that the move can be performed at the given location.
  • If check and perform are both false, then this routine does nothing and just returns true. (There is no reason to use this combination of arguments.)

The location of this move is specified by the arguments crossing and side. Specifically, this move takes place around a triangle, and one of the arcs of this triangle is uppermost (in that it passes above the other two arcs). The given crossing should be the start point of this uppermost arc; that is, when following the arc forwards, crossing should be the first of the two crossings that we encounter. The additional argument side indicates on which side of the uppermost arc the third crossing is located.

You may pass a null pointer for crossing. However, in this case the move cannot be performed, which means (i) check must be true, and therefore (ii) this routine will do nothing and return false.

All crossings in this link will keep the same indices, and no crossings will be created or destroyed. Instead, the three crossings involved in this move will simply be reordered along the various segments of the link.

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 link.
Parameters
crossingidentifies the crossing at the beginning of the "uppermost" arc that features in this move, as described above.
side0 if the third crossing of the triangle is located to the left of the uppermost arc (when walking along the arc in the forward direction), or 1 if the third crossing is located on the right of the uppermost arc.
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.

◆ reflect()

void regina::Link::reflect ( )

Converts this link into its reflection.

This routine changes the sign of every crossing, but leaves the upper and lower strands the same. This operation corresponds to reflecting the link diagram about some axis in the plane.

◆ resolve()

void regina::Link::resolve ( Crossing c)

Resolves the given crossing.

The two incoming strands will switch connections with the two outgoing strands, with the result that the given crossing is removed entirely.

Note
The number of components in the link will change as a result of this operation.
Parameters
cthe crossing to resolve.

◆ reverse()

void regina::Link::reverse ( )

Reverses the orientation of every component of this link.

This routine preserves both the sign and the upper/lower positions at every crossing, but switches all incoming strands with outgoing strands and vice versa (so next() becomes prev(), and prev() becomes next()).

◆ rewrite()

template<typename Action , typename... Args>
bool regina::Link::rewrite ( int  height,
unsigned  nThreads,
ProgressTrackerOpen tracker,
Action &&  action,
Args &&...  args 
) const
inline


Explores all knot diagrams that can be reached from this via Reidemeister moves, without exceeding a given number of additional crossings.

This routine is only available for knots at the present time. If this link has multiple (or zero) components, then this routine will return immediately (as described below).

This routine iterates through all knot diagrams that can be reached from this via Reidemeister moves, without ever exceeding height additional crossings beyond the original number. With the current implementation, these diagrams could become reflected and/or reversed, and moreover each diagram will only be considered once up to reflection and/or reversal; be aware that this behaviour could change and/or become configurable in a future version of Regina.

For every such knot diagram (including this starting diagram), this routine will call action (which must be a function or some other callable object).

  • action must take at least one argument. The first argument will be of type Link&, and will reference the knot diagram that has been found. If there are any additional arguments supplied in the list args, then these will be passed as subsequent arguments to action.
  • action must return a boolean. If action ever returns true, then this indicates that processing should stop immediately (i.e., no more knot diagrams will be processed).
  • action may, if it chooses, make changes to this knot (i.e., the original knot upon which rewrite() was called). This will not affect the search: all knot diagrams that this routine visits will be obtained via Reidemeister moves from the original knot diagram, before any subsequent changes (if any) were made.
  • action may, if it chooses, make changes to the knot that is passed in its argument (though it must not delete it). This will likewise not affect the search, since the knot diagram that is passed to action will be destroyed immediately after action is called.
  • action will only be called once for each knot diagram (including this starting diagram). In other words, no knot diagram will be revisited a second time in a single call to rewrite().

This routine can be very slow and very memory-intensive, since the number of knot diagrams it visits may be exponential in the number of crossings, and it records every knot diagram that it visits (so as to avoid revisiting the same diagram again). It is highly recommended that you begin with height = 1, and if necessary try increasing height one at a time until this routine becomes too expensive to run.

If height is negative, then there will be no bound on the number of additional crossings. This means that the routine will never terminate, unless action returns true for some knot diagram that is passed to it.

If a progress tracker is passed, then the exploration of knot diagrams will take place in a new thread and this routine will return immediately.

To assist with performance, this routine can run in parallel (multithreaded) mode; simply pass the number of parallel threads in the argument nThreads. Even in multithreaded mode, if no progress tracker is passed then this routine will not return until processing has finished (i.e., either action returned true, or the search was exhausted). All calls to action will be protected by a mutex (i.e., different threads will never be calling action at the same time).

If this link does not have precisely one component, then this routine will do nothing. If no progress tracker was passed then it will immediately return false; otherwise the progress tracker will immediately be marked as finished.

Warning
By default, the arguments args will be copied (or moved) when they are passed to action. If you need to pass some argument(s) by reference, you must wrap them in std::ref or std::cref.
The API for this class has not yet been finalised. This means that the class interface may change in new versions of Regina, without maintaining backward compatibility. If you use this class directly in your own code, please watch the detailed changelogs upon new releases to see if you need to make changes to your code.
Python
Not present.
Parameters
heightthe maximum number of additional crossings to allow beyond the number of crossings originally present in this knot diagram, or a negative number if this should not be bounded.
nThreadsthe number of threads to use. If this is 1 or smaller then the routine will run single-threaded.
trackera progress tracker through which progress will be reported, or 0 if no progress reporting is required.
actiona function (or other callable object) to call upon each knot diagram that is found.
argsany additional arguments that should be passed to action, following the initial knot argument.
Returns
If a progress tracker is passed, then this routine will return true or false immediately according to whether a new thread could or could not be started. If no progress tracker is passed, then this routine will return true if some call to action returned true (thereby terminating the search early), or false if the search ran to completion.

◆ rotate()

void regina::Link::rotate ( )

Rotates this link diagram, converting it into a different diagram of the same link.

This routine keeps the sign of each crossing fixed, but switches the upper and lower strands. This operation corresponds to a 3-dimensional rotation about some axis in the plane.

◆ simplifyExhaustive()

bool regina::Link::simplifyExhaustive ( int  height = 1,
unsigned  nThreads = 1,
ProgressTrackerOpen tracker = nullptr 
)

Attempts to simplify this knot diagram using a slow but exhaustive search through the Reidemeister graph.

This routine is more powerful but much slower than intelligentSimplify().

Unlike intelligentSimplify(), this routine could potentially reflect or reverse the link.

This routine is only available for knots at the present time. If this link has multiple (or zero) components, then this routine will return immediately (as described below).

This routine will iterate through all knot diagrams that can be reached from this via Reidemeister moves, without ever exceeding height additional crossings beyond the original number.

If at any stage it finds a diagram with fewer crossings than the original, then this routine will call intelligentSimplify() to simplify the diagram further if possible and will then return true. If it cannot find a diagram with fewer crossings then it will leave this knot diagram unchanged and return false.

This routine can be very slow and very memory-intensive: the number of knot diagrams it visits may be exponential in the number of crossings, and it records every diagram that it visits (so as to avoid revisiting the same diagram again). It is highly recommended that you begin with height = 1, and if this fails then try increasing height one at a time until either you find a simplification or the routine becomes too expensive to run.

If height is negative, then there will be no bound on the number of additional crossings. This means that the routine will not terminate until a simpler diagram is found. If no simpler diagram exists then the only way to terminate this function is to cancel the operation via a progress tracker (read on for details).

If you want a fast simplification routine, you should call intelligentSimplify() instead. The benefit of simplifyExhaustive() is that, for very stubborn knot diagrams where intelligentSimplify() finds itself stuck at a local minimum, simplifyExhaustive() is able to "climb out" of such wells.

If a progress tracker is passed, then the exhaustive simplification will take place in a new thread and this routine will return immediately. In this case, you will need to use some other means to determine whether the knot diagram was eventually simplified (e.g., by examining size() after the tracker indicates that the operation has finished).

To assist with performance, this routine can run in parallel (multithreaded) mode; simply pass the number of parallel threads in the argument nThreads. Even in multithreaded mode, if no progress tracker is passed then this routine will not return until processing has finished (i.e., either the diagram was simplified or the search was exhausted).

If this routine is unable to simplify the knot diagram, then this knot diagram will not be changed.

If this link does not have precisely one component, then this routine will do nothing. If no progress tracker was passed then it will immediately return false; otherwise the progress tracker will immediately be marked as finished.

Parameters
heightthe maximum number of additional crossings to allow beyond the number of crossings originally present in this diagram, or a negative number if this should not be bounded.
nThreadsthe number of threads to use. If this is 1 or smaller then the routine will run single-threaded.
trackera progress tracker through which progress will be reported, or null if no progress reporting is required.
Returns
If a progress tracker is passed, then this routine will return true or false immediately according to whether a new thread could or could not be started. If no progress tracker is passed, then this routine will return true if and only if this diagram was successfully simplified to fewer crossings.

◆ simplifyToLocalMinimum()

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

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

End users will probably not want to call this routine. You should call intelligentSimplify() if you want a fast (and usually effective) means of simplifying a link. If this link is a knot (i.e., it has precisely one component), then you can also call simplifyExhaustive() if you are still stuck and you want to try a slower but more powerful method instead.

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

This routine will never reflect or reverse the link.

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::Link::size ( ) const
inline

Returns the number of crossings in this link.

Note that a link can have more components than crossings (since it may contain additional zero-crossing unknot components).

Returns
the number of crossings.

◆ str()

std::string regina::Output< Packet , 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.

◆ strand()

StrandRef regina::Link::strand ( int  id) const
inline

Returns the strand in the link with the given integer ID.

Each strand ID is of the form 2c+s, where c is the index of the crossing, and s is 0 or 1 for the lower or upper strand respectively. A null strand reference (as used to indicate 0-crossing unknot components) has an ID of -1.

Parameters
idan integer between -1 and 2*size()-1 inclusive.
Returns
the strand of this link with the corresponding ID.
See also
StrandRef::id()

◆ swapContents()

void regina::Link::swapContents ( Link other)

Swaps the contents of this and the given link.

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::Link::translate ( const StrandRef other) const
inline

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

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

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

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

◆ useTreeDecomposition()

void regina::Link::useTreeDecomposition ( const TreeDecomposition td)
inline

Instructs Regina to use the given tree decomposition as the starting point whenever it needs a tree decomposition for this link.

For some link routines, including niceTreeDecomposition() as well as computations such as jones() that support the option ALG_TREEWIDTH, Regina needs a tree decomposition of the planar 4-valent multigraph formed by this link diagram.

By default, Regina will compute (and then cache) such a tree decomposition itself, using in-built greedy heuristics. This routine allows you to supply your own tree decomposition (which, for example, might be a smaller-width tree decomposition that you found using third-party software). By supplying your own tree decomposition td through this routine, Regina will throw away any pre-computed tree decomposition that it has cached, and will instead cache td for future use instead.

Regina will not claim ownership of td, and will not edit it in any way. Instead, it will make a deep copy of td and then modify this copy for its purposes.

In particular, td does not need to be a nice tree decomposition (indeed, it does not need to have any special properties beyond the definition of a tree decomposition). Regina will automatically create a nice tree decomposition from it if td is not nice already.

Parameters
tda tree decomposition of the planar 4-valent multigraph formed by this link diagram.

◆ utf8()

std::string regina::Output< Packet , 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.

◆ writePACE()

void regina::Link::writePACE ( std::ostream &  out) const


Outputs the underlying planar 4-valent multigraph using the PACE text format.

The text format is described in detail at https://pacechallenge.wordpress.com/pace-2016/track-a-treewidth/ .

In summary, the output will consist of several lines of text:

  • If this link has a packet label, then the output will begin with a descriptive comment line of the form c label. Otherwise this initial comment line will be omitted.
  • Next will be a line of the form p tw num_vertices num_edges. Note that, since the underlying graph comes from a link diagram, we will always have num_edges equal to twice num_vertices.
  • Following this will be num_edges lines, one for each edge, each of the form u v, indicating an edge from vertex number u to vertex number v. In this format, vertices are numbered 1,2,...,num_vertices.

An example of this text format is as follows:

          c Figure eight knot
          p tw 4 8
          1 2
          1 4
          1 2
          2 3
          3 4
          1 3
          3 4
          2 4
Python
The out argument is not present; instead standard output is assumed.
Parameters
outthe output stream to which to write.
      @see https://pacechallenge.wordpress.com/pace-2016/track-a-treewidth/

◆ writeTextLong()

virtual void regina::Link::writeTextLong ( std::ostream &  out) const
overridevirtual


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

This may be reimplemented by subclasses, but the parent Packet class offers a reasonable default implementation.

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

Reimplemented from regina::Packet.

◆ writeTextShort()

virtual void regina::Link::writeTextShort ( std::ostream &  out) const
overridevirtual


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

This must be reimplemented by subclasses.

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

Implements regina::Packet.

◆ writeXMLPacketData()

virtual void regina::Link::writeXMLPacketData ( std::ostream &  out) const
overrideprotectedvirtual

Writes a chunk of XML containing the data for this packet only.

You may assume that the packet opening tag (including the packet type and label) has already been written, and that all child packets followed by the corresponding packet closing tag will be written immediately after this routine is called. This routine need only write the internal data stored in this specific packet.

Parameters
outthe output stream to which the XML should be written.

Implements regina::Packet.

◆ writhe()

long regina::Link::writhe ( ) const
inline

Returns the writhe of this link diagram.

This is not an invariant of the link; instead it depends on the particular link diagram. It is computed as the sum of the signs of all crossings. It is preserved under Reidemeister moves II and III, but not I.

Returns
the writhe.

Member Data Documentation

◆ homflyAZVarX

const char* regina::Link::homflyAZVarX
static

The name of the first variable used in the variant of the HOMFLY polynomial as returned by homflyAZ().

This is provided to help with pretty-printing HOMFLY polynomials for human consumption.

Since homflyAZ() returns a Laurent polynomial in alpha and z, this string just contains the mathematical symbol alpha (encoded in UTF-8).

To pretty-print this HOMFLY polynomial for human consumption, you can call Laurent2::str(Link::homflyAZVarX, Link::homflyAZVarY).

◆ homflyAZVarY

const char* regina::Link::homflyAZVarY
static

The name of the second variable used in the variant of the HOMFLY polynomial as returned by homflyAZ().

This is provided to help with pretty-printing HOMFLY polynomials for human consumption.

Since homflyAZ() returns a Laurent polynomial in alpha and z, this string just contains the single character z.

To pretty-print this HOMFLY polynomial for human consumption, you can call Laurent2::str(Link::homflyAZVarX, Link::homflyAZVarY).

◆ homflyLMVarX

const char* regina::Link::homflyLMVarX
static

The name of the first variable used in the variant of the HOMFLY polynomial as returned by homflyLM().

This is provided to help with pretty-printing HOMFLY polynomials for human consumption.

Since homflyLM() returns a Laurent polynomial in l and m, this string just contains the mathematical script symbol for l (encoded in UTF-8).

To pretty-print this HOMFLY polynomial for human consumption, you can call Laurent2::str(Link::homflyLMVarX, Link::homflyLMVarY).

◆ homflyLMVarY

const char* regina::Link::homflyLMVarY
static

The name of the second variable used in the variant of the HOMFLY polynomial as returned by homflyLM().

This is provided to help with pretty-printing HOMFLY polynomials for human consumption.

Since homflyLM() returns a Laurent polynomial in l and m, this string just contains the single character m.

To pretty-print this HOMFLY polynomial for human consumption, you can call Laurent2::str(Link::homflyLMVarX, Link::homflyLMVarY).

◆ homflyVarX

const char* regina::Link::homflyVarX
static

The name of the first variable used in the variant of the HOMFLY polynomial as returned by homfly().

This is simply an alias for homflyAZVarX. See the documentation for homflyAZVarX for further details.

◆ homflyVarY

const char* regina::Link::homflyVarY
static

The name of the second variable used in the variant of the HOMFLY polynomial as returned by homfly().

This is simply an alias for homflyAZVarY. See the documentation for homflyAZVarY for further details.

◆ jonesVar

const char* regina::Link::jonesVar
static

The name of the variable used in the Jones polynomial, as returned by jones().

This is provided to help with pretty-printing Jones polynomials for human consumption.

Since jones() returns a Laurent polynomial in the square root of t, this string is just a human-readable representation of the square root of t (encoded in UTF-8).

To pretty-print the Jones polynomial for human consumption, you can call Laurent::str(Link::jonesVar).


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