Regina Calculation Engine
|
Represents a directed knot or link in the 3-sphere. More...
#include <link/link.h>
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 ©) | |
Constructs a new copy of the given link. More... | |
Link (const Link ©, 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... | |
Crossing * | crossing (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... | |
Link * | parallel (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 TreeDecomposition & | niceTreeDecomposition () 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 | |
Packet * | parent () const |
Determines the parent packet in the tree structure. More... | |
Packet * | firstChild () const |
Determines the first child of this packet in the tree structure. More... | |
Packet * | lastChild () const |
Determines the last child of this packet in the tree structure. More... | |
Packet * | nextSibling () const |
Determines the next sibling of this packet in the tree structure. More... | |
Packet * | prevSibling () const |
Determines the previous sibling of this packet in the tree structure. More... | |
Packet * | root () 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... | |
Packet * | nextTreePacket () |
Finds the next packet after this in a complete depth-first iteration of the entire tree structure to which this packet belongs. More... | |
const Packet * | nextTreePacket () const |
Finds the next packet after this in a complete depth-first iteration of the entire tree structure to which this packet belongs. More... | |
Packet * | nextTreePacket (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 Packet * | nextTreePacket (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... | |
Packet * | firstTreePacket (const std::string &type) |
Finds the first packet of the requested type in a complete depth-first iteration of the tree structure. More... | |
const Packet * | firstTreePacket (const std::string &type) const |
Finds the first packet of the requested type in a complete depth-first iteration of the tree structure. More... | |
Packet * | findPacketLabel (const std::string &label) |
Finds the packet with the requested label in the tree or subtree for which this packet is matriarch. More... | |
const Packet * | findPacketLabel (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 | |
Packet * | clone (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 XMLPacketReader * | xmlReader (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 Packet * | internalClonePacket (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 Link * | fromData (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 Link * | fromKnotSig (const std::string &sig) |
Recovers a knot diagram from its signature. More... | |
static Link * | fromGauss (const std::string &str) |
Creates a new knot from a classical Gauss code. More... | |
template<typename Iterator > | |
static Link * | fromGauss (Iterator begin, Iterator end) |
Creates a new knot from a classical Gauss code. More... | |
static Link * | fromOrientedGauss (const std::string &str) |
Creates a new knot from an "oriented" variant of the Gauss code. More... | |
template<typename Iterator > | |
static Link * | fromOrientedGauss (Iterator begin, Iterator end) |
Creates a new knot from an "oriented" variant of the Gauss code. More... | |
static Link * | fromJenkins (const std::string &str) |
Builds a link from the text representation described by Bob Jenkins. More... | |
static Link * | fromJenkins (std::istream &in) |
Builds a link from the text representation described by Bob Jenkins. More... | |
static Link * | fromDT (const std::string &str) |
Creates a new knot from either alphabetical or numerical Dowker-Thistlethwaite notation. More... | |
template<typename Iterator > | |
static Link * | fromDT (Iterator begin, Iterator end) |
Creates a new knot from an integer sequence using the numerical variant of Dowker-Thistlethwaite notation. More... | |
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).
|
inherited |
The type of object being pointed to.
|
inline |
Constructs an empty link.
This will have zero components.
|
inline |
Constructs the unlink with the given number of components.
unknots | the number of (unknotted) components in the new unlink. |
|
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.
copy | the link to copy. |
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.
copy | the link to copy. |
cloneProps | true 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. |
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.
description | a string that describes a knot or link. |
|
inline |
Destroys this link.
The Crossing objects contained in this link will also be destroyed.
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:
alg | the 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. |
tracker | a progress tracker through which progress will be reported, or null if no progress reporting is required. |
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:
+
or -
), concatenated together, giving the signs of the crossings in order from crossing 0 to crossing size()-1;( 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.
void regina::Link::change | ( | Crossing * | c | ) |
Switches the upper and lower strands of the given crossing.
c | the crossing to change. |
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.
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:
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.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.
simplify | true if and only if the triangulation of the complement should be simplified (thereby losing information about the orientation), as described above. |
|
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
).
index | the index of the requested component. This must be between 0 and countComponents()-1 inclusive. |
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.
other | the link with which this should be composed. |
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
a | the first of the two crossings to examine. |
b | the second of the two crossings to examine. |
true
if and only if the two given crossings are connected.
|
inline |
Returns the number of components in this link.
|
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.
index | the index of the requested crossing. This must be between 0 and size()-1 inclusive. |
|
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.
true
if and only if this packet depends on its parent. Implements regina::Packet.
|
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.
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
,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.
alpha | true to use alphabetical notation, or false (the default) to use numerical notation. |
true
and the knot has more than 26 crossings. 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
,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.
out | the output stream to which to write. |
alpha | true to use alphabetical notation, or false (the default) to use numerical notation. |
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.
|
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:
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:
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).
crossingSigns | a list containing the signs of the crossings; each sign must be either +1 or -1. |
components | one list for each link component that describes the crossings that are visited along that component, as described in the detailed notes above. |
null
if the input was found to be invalid.
|
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:
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.
str | either the alphabetical or numerical Dowker-Thistlethwaite notation for a knot, as described above. |
null
if the input was found to be invalid.
|
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.
begin | an iterator that points to the beginning of the sequence of integers for the Dowker-Thistlethwaite notation for a knot. |
end | an iterator that points past the end of the sequence of integers for the Dowker-Thistlethwaite notation for a knot. |
null
if the input was found to be invalid.
|
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:
The format works as follows:
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.
str | a classical Gauss code for a knot, as described above. |
null
if the input was found to be invalid.
|
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.
begin | an iterator that points to the beginning of the sequence of integers for a classical Gauss code. |
end | an iterator that points past the end of the sequence of integers for a classical Gauss code. |
null
if the input was found to be invalid.
|
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:
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.
str | a string containing a sequence of integers separated by whitespace that describes a link, as detailed above. |
null
if the input was found to be invalid.
|
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).
in | an input stream that begins with a sequence of integers separated by whitespace that describes a link. |
null
if the input was found to be invalid.
|
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.
sig | the signature of the knot diagram to construct. Note that signatures are case-sensitive. |
null
if the given string was not a valid knot signature.
|
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:
The format works as follows:
+<k
, -<k
, +>k
or ->k
, where:+
indicates that you are passing over the crossing labelled k, and the symbol -
indicates that you are passing under the crossing labelled k;<
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.
str | an "oriented" Gauss code for a knot, as described above. |
null
if the input was found to be invalid.
|
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.
const char*
) or a C++-style string (which can be cast to const std::string&
).begin | an iterator that points to the beginning of the sequence of tokens for an "oriented" Gauss code. |
end | an iterator that points past the end of the sequence of tokens for an "oriented" Gauss code. |
null
if the input was found to be invalid. 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.
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.
out | the output stream to which to write. |
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.
true
if and only if there is a pass move that reduces the number of crossings.
|
inlineinherited |
Is there one or more SafePtr currently pointing to this object?
|
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.
alg | the 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. |
tracker | a progress tracker through which progress will be reported, or null if no progress reporting is required. |
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:
alg | the 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. |
tracker | a progress tracker through which progress will be reported, or null if no progress reporting is required. |
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:
alg | the 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. |
tracker | a progress tracker through which progress will be reported, or null if no progress reporting is required. |
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().
p | the first parameter of the new torus link; this must be non-negative. |
q | the second parameter of the new torus link; this must also be non-negative. |
positive | true if the crossings in the new torus link should be positive, or false if they should be negative. |
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.
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.
parent | the parent beneath which the new packet will eventually be inserted. |
Implements regina::Packet.
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.
true
if this is an alternating diagram, or false
if this is a non-alternating diagram.
|
inline |
Determines whether this link is empty.
An empty link is one with no components at all.
true
if and only if this link is empty. 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.
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.
out | the output stream to which to write. |
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:
1/t + 1/t^3 - 1/t^4
, and so this routine returns the Laurent polynomial x^-2 + x^-6 - x^-8
.-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:
alg | the 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. |
tracker | a progress tracker through which progress will be reported, or null if no progress reporting is required. |
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.
useReflection | true 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). |
useReversal | true 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). |
|
inline |
|
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).
true
if and only if this property is already known.
|
inline |
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.
|
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().
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.
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.
out | the output stream to which to write. |
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.
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:
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.
k | the number of parallel copies to create. This must be non-negative. |
framing | the framing under which these copies will be parallel. |
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.
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
.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.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.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
.
true
but check is false
, then it must be known in advance that this move can be performed at the given location. crossing | identifies the crossing to be removed. |
check | true if we are to check whether the move can be performed at the given location. |
perform | true if we should actually perform the move. |
true
, this function returns true
if and only if the move can be performed. If check is false
, this function always returns true
. 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.
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
.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.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.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.
true
but check is false
, then it must be known in advance that this move can be performed at the given location. arc | identifies the arc of the link in which the new twist will be introduced, as described above. |
side | 0 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. |
sign | the sign of the new crossing that will be introduced as part of the twist; this must be +1 or -1. |
check | true if we are to check whether the move can be performed at the given location. |
perform | true if we should actually perform the move. |
true
, this function returns true
if and only if the move can be performed. If check is false
, this function always returns true
. 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.
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
.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.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.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
.
true
but check is false
, then it must be known in advance that this move can be performed at the given location. arc | identifies one of the arcs of the bigon about which the move will be performed, as described above. |
check | true if we are to check whether the move is legal. |
perform | true if we should actually perform the move. |
true
, this function returns true
if and only if the requested move is legal. If check is false
, this function always returns 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.
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
.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.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.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
.
true
but check is false
, then it must be known in advance that this move can be performed at the given location. crossing | identifies the crossing at the beginning of the "upper" arc that features in this move, as described above. |
check | true if we are to check whether the move is legal. |
perform | true if we should actually perform the move. |
true
, this function returns true
if and only if the requested move is legal. If check is false
, this function always returns true
. 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.
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
.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.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.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.
true
but check is false
, then it must be known in advance that this move can be performed at the given location. upperArc | identifies the arc of the link which will be passed over the other, as described above. |
upperSide | 0 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. |
lowerArc | identifies the arc of the link which will be passed beneath the other, as described above. |
lowerSide | 0 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. |
check | true if we are to check whether the move can be performed at the given location. |
perform | true if we should actually perform the move. |
true
, this function returns true
if and only if the move can be performed. If check is false
, this function always returns true
. 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.
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
.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.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.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.
true
but check is false
, then it must be known in advance that this move can be performed at the given location. arc | identifies one of the arcs of the triangle about which the move will be performed, as described above. |
side | 0 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. |
check | true if we are to check whether the move can be performed at the given location. |
perform | true if we should actually perform the move. |
true
, this function returns true
if and only if the move can be performed. If check is false
, this function always returns 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.
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
.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.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.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.
true
but check is false
, then it must be known in advance that this move can be performed at the given location. crossing | identifies the crossing at the beginning of the "uppermost" arc that features in this move, as described above. |
side | 0 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. |
check | true if we are to check whether the move can be performed at the given location. |
perform | true if we should actually perform the move. |
true
, this function returns true
if and only if the move can be performed. If check is false
, this function always returns true
. 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.
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.
c | the crossing to resolve. |
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()).
|
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).
true
, then this indicates that processing should stop immediately (i.e., no more knot diagrams will be processed).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.
height | the 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. |
nThreads | the number of threads to use. If this is 1 or smaller then the routine will run single-threaded. |
tracker | a progress tracker through which progress will be reported, or 0 if no progress reporting is required. |
action | a function (or other callable object) to call upon each knot diagram that is found. |
args | any additional arguments that should be passed to action, following the initial knot argument. |
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. 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.
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.
height | the 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. |
nThreads | the number of threads to use. If this is 1 or smaller then the routine will run single-threaded. |
tracker | a progress tracker through which progress will be reported, or null if no progress reporting is required. |
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. 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.
perform | true if we are to perform the simplifications, or false if we are only to investigate whether simplifications are possible (defaults to true ). |
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.
|
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).
|
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.
__str__()
.
|
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.
id | an integer between -1 and 2*size()-1 inclusive. |
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.
other | the link whose contents should be swapped with this. |
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.
other | the strand reference to translate. |
|
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.
td | a tree decomposition of the planar 4-valent multigraph formed by this link diagram. |
|
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.
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:
c label
. Otherwise this initial comment line will be omitted.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.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
out | the output stream to which to write. @see https://pacechallenge.wordpress.com/pace-2016/track-a-treewidth/ |
|
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.
out | the output stream to which to write. |
Reimplemented from regina::Packet.
|
overridevirtual |
Writes a short text representation of this object to the given output stream.
This must be reimplemented by subclasses.
out | the output stream to which to write. |
Implements regina::Packet.
|
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.
out | the output stream to which the XML should be written. |
Implements regina::Packet.
|
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.
|
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)
.
|
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)
.
|
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)
.
|
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)
.
|
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.
|
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.
|
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)
.