Regina Calculation Engine
Classes | Typedefs | Enumerations | Enumerator | Functions | Variables | Friends
Knots and Links

Knots and links in the 3-sphere. More...

Classes

class  regina::ExampleLink
 This class offers routines for constructing ready-made examples of knots and links. More...
 
class  regina::Laurent< T >
 Represents a single-variable Laurent polynomial with coefficients of type T. More...
 
class  regina::Laurent2< T >
 Represents a Laurent polynomial in the two variables x, y with coefficients of type T. More...
 
class  regina::Triangulation< dim >
 A dim-dimensional triangulation, built by gluing together dim-dimensional simplices along their (dim-1)-dimensional facets. More...
 
class  regina::StrandRef
 A reference to one of the two strands of a link that pass each other at a crossing. More...
 
class  regina::Crossing
 Represents a single crossing in a link diagram. More...
 
class  regina::Link
 Represents a directed knot or link in the 3-sphere. More...
 
class  regina::CrossingIterator
 Iterates through all crossings of a link. More...
 
class  regina::ArcIterator
 Iterates through all directed arcs of a knot or link. More...
 
struct  std::iterator_traits< regina::CrossingIterator >
 
struct  std::iterator_traits< regina::ArcIterator >
 
class  regina::ModelLinkGraphArc
 A reference to an outgoing edge from a node of a model graph for a knot or link. More...
 
class  regina::ModelLinkGraphNode
 Represents a single node in a model graph for a knot or link. More...
 
class  regina::ModelLinkGraph
 Represents an undirected 4-valent planar graph with a specific planar embedding. More...
 
class  regina::ModelLinkGraphCells
 Describes the cellular decomposition of the sphere that is induced by a given planar 4-valent graph. More...
 
class  regina::Tangle
 Represents a 2-tangle in the 3-ball. More...
 
class  regina::XMLLinkReader
 An XML packet reader that reads a single knot or link. More...
 
class  regina::XMLLinkCrossingsReader
 Helper class that reads the XML element containing basic information about the crossings of a knot or link. More...
 
class  regina::XMLLinkConnectionsReader
 Helper class that reads the XML element containing information on connections between crossings of a knot or link. More...
 
class  regina::XMLLinkComponentsReader
 Helper class that reads the XML element containing information about the individual components of a link. More...
 

Typedefs

typedef int std::iterator_traits< regina::CrossingIterator >::difference_type
 
typedef regina::Crossingstd::iterator_traits< regina::CrossingIterator >::value_type
 
typedef regina::Crossing *const * std::iterator_traits< regina::CrossingIterator >::pointer
 
typedef regina::Crossing *const & std::iterator_traits< regina::CrossingIterator >::reference
 
typedef std::input_iterator_tag std::iterator_traits< regina::CrossingIterator >::iterator_category
 
typedef int std::iterator_traits< regina::ArcIterator >::difference_type
 
typedef regina::StrandRef std::iterator_traits< regina::ArcIterator >::value_type
 
typedef regina::StrandRef const * std::iterator_traits< regina::ArcIterator >::pointer
 
typedef regina::StrandRef std::iterator_traits< regina::ArcIterator >::reference
 
typedef std::input_iterator_tag std::iterator_traits< regina::ArcIterator >::iterator_category
 
typedef void(* regina::ModelLinkGraph::Use) (Link *, void *)
 A routine that can do arbitrary processing upon a knot or link. More...
 

Enumerations

enum  regina::Framing { regina::FRAMING_SEIFERT = 1 , regina::FRAMING_BLACKBOARD = 2 }
 Indicates one of the standard framings of a knot or link. More...
 

Functions

static Linkregina::ExampleLink::unknot ()
 Returns a zero-crossing diagram of the unknot. More...
 
static Linkregina::ExampleLink::monster ()
 Returns the monster unknot, a 10-crossing diagram of the unknot that is difficult to untangle. More...
 
static Linkregina::ExampleLink::gordian ()
 Returns Haken's Gordian unknot, a 141-crossing diagram of the unknot that is difficult to untangle. More...
 
static Linkregina::ExampleLink::trefoilLeft ()
 Returns a three-crossing diagram of the left-hand trefoil. More...
 
static Linkregina::ExampleLink::trefoilRight ()
 Returns a three-crossing diagram of the right-hand trefoil. More...
 
static Linkregina::ExampleLink::trefoil ()
 Returns a three-crossing diagram of the right-hand trefoil. More...
 
static Linkregina::ExampleLink::figureEight ()
 Returns a four-crossing diagram of the figure eight knot. More...
 
static Linkregina::ExampleLink::hopf ()
 Returns a two-crossing diagram of the Hopf link. More...
 
static Linkregina::ExampleLink::whitehead ()
 Returns a five-crossing diagram of the Whitehead link. More...
 
static Linkregina::ExampleLink::borromean ()
 Returns a six-crossing diagram of the Borromean rings. More...
 
static Linkregina::ExampleLink::conway ()
 Returns the 11-crossing Conway knot. More...
 
static Linkregina::ExampleLink::kinoshitaTerasaka ()
 Returns the 11-crossing Kinoshita-Terasaka knot. More...
 
static Linkregina::ExampleLink::torus (int p, int q)
 Returns the (p,q) torus link. More...
 
static Linkregina::ExampleLink::gst ()
 Returns a 48-crossing potential counterexample to the slice-ribbon conjecture, as described by Gompf, Scharlemann and Thompson. More...
 
 regina::StrandRef::StrandRef ()
 Initialises this to a null reference. More...
 
 regina::StrandRef::StrandRef (Crossing *crossing, int strand)
 Initialises this to the given strand of the given crossing. More...
 
 regina::StrandRef::StrandRef (const StrandRef &)=default
 Default copy constructor. More...
 
Crossingregina::StrandRef::crossing () const
 The crossing that this reference points to. More...
 
int regina::StrandRef::strand () const
 Indicates whether this reference points to the upper or lower strand of the relevant crossing. More...
 
int regina::StrandRef::id () const
 An integer that uniquely identifies this strand within the link. More...
 
bool regina::StrandRef::operator== (const StrandRef &rhs) const
 Tests whether this and the given reference are identical. More...
 
bool regina::StrandRef::operator!= (const StrandRef &rhs) const
 Tests whether this and the given reference are not identical. More...
 
StrandRefregina::StrandRef::operator= (const StrandRef &)=default
 Default assignment operator. More...
 
StrandRefregina::StrandRef::operator++ ()
 Moves this reference forward along the direction of the link until it reaches the next crossing. More...
 
StrandRef regina::StrandRef::operator++ (int)
 Moves this reference forward along the direction of the link until it reaches the next crossing. More...
 
StrandRefregina::StrandRef::operator-- ()
 Moves this reference backward against the direction of the link until it reaches the previous crossing. More...
 
StrandRef regina::StrandRef::operator-- (int)
 Moves this reference backward against the direction of the link until it reaches the previous crossing. More...
 
StrandRef regina::StrandRef::next () const
 Returns the crossing reference that comes immediately after this when walking forward along the direction of the link. More...
 
StrandRef regina::StrandRef::prev () const
 Returns the crossing reference that comes immediately before this when walking backward against the direction of the link. More...
 
void regina::StrandRef::jump ()
 Jumps to the other strand at the same crossing. More...
 
 regina::StrandRef::operator bool () const
 Tests whether this is a non-null reference. More...
 
std::ostream & regina::operator<< (std::ostream &out, const StrandRef &s)
 Writes a depiction of the given strand reference to the given output stream. More...
 
int regina::Crossing::index () const
 Returns the index of this crossing within the overall link. More...
 
int regina::Crossing::sign () const
 Returns the sign of this crossing. More...
 
StrandRef regina::Crossing::upper ()
 Returns a reference to the strand running over this crossing. More...
 
StrandRef regina::Crossing::lower ()
 Returns a reference to the strand running under this crossing. More...
 
StrandRef regina::Crossing::over ()
 Returns a reference to the strand running over this crossing. More...
 
StrandRef regina::Crossing::under ()
 Returns a reference to the strand running under this crossing. More...
 
StrandRef regina::Crossing::strand (int which)
 Returns a reference to one of the two strands of the link that pass each other at this crossing. More...
 
StrandRef regina::Crossing::next (int strand) const
 Returns the crossing reference that immediately follows this when walking forward in the direction of the link along one of the two strands that pass at this crossing. More...
 
StrandRef regina::Crossing::prev (int strand) const
 Returns the crossing reference that immediately precedes this when walking backward against the direction of the link along one of the two strands that pass at this crossing. More...
 
void regina::Crossing::writeTextShort (std::ostream &out) const
 Writes a short text representation of this object to the given output stream. More...
 
void regina::Crossing::writeTextLong (std::ostream &out) const
 Writes a detailed text representation of this object to the given output stream. More...
 
 regina::Crossing::Crossing (const Crossing &)=delete
 
Crossingregina::Crossing::operator= (const Crossing &)=delete
 
 regina::CrossingIterator::CrossingIterator ()
 Creates a singular iterator. More...
 
 regina::CrossingIterator::CrossingIterator (const CrossingIterator &)=default
 Default copy constructor. More...
 
 regina::CrossingIterator::CrossingIterator (const Link &link, size_t index=0)
 Creates a new iterator pointing to the given crossing of the given link. More...
 
CrossingIteratorregina::CrossingIterator::operator++ ()
 Preincrement operator. More...
 
CrossingIterator regina::CrossingIterator::operator++ (int)
 Postincrement operator. More...
 
Crossingregina::CrossingIterator::operator* () const
 Returns the crossing to which this iterator points. More...
 
CrossingIteratorregina::CrossingIterator::operator= (const CrossingIterator &)=default
 Default assignment operator. More...
 
bool regina::CrossingIterator::operator== (const CrossingIterator &rhs) const
 Tests whether this and the given iterator are equal. More...
 
bool regina::CrossingIterator::operator!= (const CrossingIterator &rhs) const
 Tests whether this and the given iterator are different. More...
 
 regina::ArcIterator::ArcIterator ()
 Creates a singular iterator. More...
 
 regina::ArcIterator::ArcIterator (const ArcIterator &)=default
 Default copy constructor. More...
 
 regina::ArcIterator::ArcIterator (const Link &link, size_t crossing=0, bool upper=false)
 Creates a new iterator pointing to the arc exiting the given strand of the given crossing of the given link. More...
 
ArcIteratorregina::ArcIterator::operator++ ()
 Preincrement operator. More...
 
ArcIterator regina::ArcIterator::operator++ (int)
 Postincrement operator. More...
 
StrandRef regina::ArcIterator::operator* () const
 Returns the directed arc to which this iterator points. More...
 
ArcIteratorregina::ArcIterator::operator= (const ArcIterator &)=default
 Default assignment operator. More...
 
bool regina::ArcIterator::operator== (const ArcIterator &rhs) const
 Tests whether this and the given iterator are equal. More...
 
bool regina::ArcIterator::operator!= (const ArcIterator &rhs) const
 Tests whether this and the given iterator are different. More...
 
 regina::ModelLinkGraphArc::ModelLinkGraphArc ()
 Initialises this to a null arc. More...
 
 regina::ModelLinkGraphArc::ModelLinkGraphArc (ModelLinkGraphNode *node, int arc)
 Initialises this to the given arc exiting the given node of a model graph. More...
 
 regina::ModelLinkGraphArc::ModelLinkGraphArc (const ModelLinkGraphArc &)=default
 Default copy constructor. More...
 
ModelLinkGraphNoderegina::ModelLinkGraphArc::node () const
 The node of the model graph from which this arc exits. More...
 
int regina::ModelLinkGraphArc::arc () const
 Indicates which arc this is amongst the four arcs exiting the underlying node of the model graph. More...
 
bool regina::ModelLinkGraphArc::operator== (const ModelLinkGraphArc &rhs) const
 Tests whether this and the given arc reference are identical. More...
 
bool regina::ModelLinkGraphArc::operator!= (const ModelLinkGraphArc &rhs) const
 Tests whether this and the given arc reference are not identical. More...
 
ModelLinkGraphArcregina::ModelLinkGraphArc::operator= (const ModelLinkGraphArc &)=default
 Default assignment operator. More...
 
ModelLinkGraphArc regina::ModelLinkGraphArc::opposite () const
 Returns the arc that exits the same node as this, but from the opposite side. More...
 
ModelLinkGraphArc regina::ModelLinkGraphArc::traverse () const
 Returns the same edge of the model graph, but seen from the other endpoint. More...
 
ModelLinkGraphArc regina::ModelLinkGraphArc::next () const
 Returns the next arc after this when walking through the graph as though it were a link, in a direction away from the current node. More...
 
ModelLinkGraphArc regina::ModelLinkGraphArc::prev () const
 Returns the previous arc before this when walking through the graph as though it were a link, in a direction away from the* current node. More...
 
ModelLinkGraphArcregina::ModelLinkGraphArc::operator++ ()
 Changes to the next outgoing link arc from the same node. More...
 
ModelLinkGraphArc regina::ModelLinkGraphArc::operator++ (int)
 Changes to the next outgoing link arc from the same node. More...
 
ModelLinkGraphArcregina::ModelLinkGraphArc::operator-- ()
 Changes to the previous outgoing link arc from the same node. More...
 
ModelLinkGraphArc regina::ModelLinkGraphArc::operator-- (int)
 Changes to the previous outgoing link arc from the same node. More...
 
 regina::ModelLinkGraphArc::operator bool () const
 Tests whether this is a non-null arc. More...
 
std::ostream & regina::operator<< (std::ostream &out, const ModelLinkGraphArc &a)
 Writes a depiction of the given arc reference to the given output stream. More...
 
int regina::ModelLinkGraphNode::index () const
 Returns the index of this node within the overall graph. More...
 
ModelLinkGraphArc regina::ModelLinkGraphNode::arc (int which)
 Returns a reference to one of the four arcs of the graph that exit this node. More...
 
const ModelLinkGraphArcregina::ModelLinkGraphNode::adj (int which) const
 Returns the arc at the other end of the given graph edge that exits this node. More...
 
void regina::ModelLinkGraphNode::writeTextShort (std::ostream &out) const
 Writes a short text representation of this node to the given output stream. More...
 
void regina::ModelLinkGraphNode::writeTextLong (std::ostream &out) const
 Writes a detailed text representation of this node to the given output stream. More...
 
 regina::ModelLinkGraphNode::ModelLinkGraphNode (const ModelLinkGraphNode &)=delete
 
ModelLinkGraphNoderegina::ModelLinkGraphNode::operator= (const ModelLinkGraphNode &)=delete
 
 regina::ModelLinkGraph::ModelLinkGraph ()
 Constructs an empty graph. More...
 
 regina::ModelLinkGraph::ModelLinkGraph (const ModelLinkGraph &copy)
 Constructs a new copy of the given graph. More...
 
 regina::ModelLinkGraph::~ModelLinkGraph ()
 Destroys this graph. More...
 
size_t regina::ModelLinkGraph::size () const
 Returns the number of nodes in this graph. More...
 
ModelLinkGraphNoderegina::ModelLinkGraph::node (size_t index) const
 Returns the node at the given index within this graph. More...
 
void regina::ModelLinkGraph::swapContents (ModelLinkGraph &other)
 Swaps the contents of this and the given graph. More...
 
void regina::ModelLinkGraph::reflect ()
 Converts this graph into its reflection. More...
 
const ModelLinkGraphCellsregina::ModelLinkGraph::cells () const
 Returns details of the cellular decomposition of the sphere that is induced by this graph. More...
 
std::pair< ModelLinkGraphArc, ModelLinkGraphArcregina::ModelLinkGraph::findFlype (const ModelLinkGraphArc &from) const
 TODO: Flype is between arc– and arc, i.e., over the region defined by cell(arc). More...
 
ModelLinkGraphregina::ModelLinkGraph::flype (const ModelLinkGraphArc &from, const ModelLinkGraphArc &left, const ModelLinkGraphArc &right) const
 TODO: Document. More...
 
ModelLinkGraphregina::ModelLinkGraph::flype (const ModelLinkGraphArc &from) const
 TODO: Document. More...
 
void regina::ModelLinkGraph::generateMinimalLinks (Use use, void *useArgs=0) const
 TODO: Document. More...
 
std::string regina::ModelLinkGraph::plantri () const
 Outputs this graph in the ASCII text format used by plantri. More...
 
std::string regina::ModelLinkGraph::canonicalPlantri (bool useReflection=true, bool tight=false) const
 Outputs a text representation of this graph in the plantri ASCII format, using a canonical relabelling of nodes and arcs, and with optional compression. More...
 
void regina::ModelLinkGraph::writeTextShort (std::ostream &out) const
 Writes a short text representation of this graph to the given output stream. More...
 
void regina::ModelLinkGraph::writeTextLong (std::ostream &out) const
 Writes a detailed text representation of this graph to the given output stream. More...
 
static ModelLinkGraphregina::ModelLinkGraph::fromPlantri (const std::string &plantri)
 Builds a graph from a line of plantri output. More...
 
ModelLinkGraphregina::ModelLinkGraph::operator= (const ModelLinkGraph &)=delete
 
 regina::ModelLinkGraphCells::~ModelLinkGraphCells ()
 Destroys this cellular decomposition. More...
 
bool regina::ModelLinkGraphCells::isValid () const
 Determines whether the underlying graph is non-empty with a planar embedding, assuming that it is already known to be connected. More...
 
size_t regina::ModelLinkGraphCells::countCells () const
 Returns the number of 2-cells in this cellular decomposition. More...
 
const ModelLinkGraphArcregina::ModelLinkGraphCells::arc (size_t cell, size_t which) const
 Returns the given arc along the boundary of the given 2-cell. More...
 
size_t regina::ModelLinkGraphCells::size (size_t cell) const
 Returns the number of arcs aloung the boundary of the given 2-cell. More...
 
const ModelLinkGraphArcregina::ModelLinkGraphCells::begin (size_t cell) const
 Returns the beginning of an iterator range for walking around the boundary of the given 2-cell. More...
 
const ModelLinkGraphArcregina::ModelLinkGraphCells::end (size_t cell) const
 Returns the end of an iterator range for walking around the boundary of the given 2-cell. More...
 
size_t regina::ModelLinkGraphCells::cell (const ModelLinkGraphArc &arc) const
 Returns the 2-cell that lies to the left of the given arc. More...
 
size_t regina::ModelLinkGraphCells::cellPos (const ModelLinkGraphArc &arc) const
 Returns where the given arc appears along the boundary of the 2-cell to its left. More...
 
void regina::ModelLinkGraphCells::writeTextShort (std::ostream &out) const
 Writes a short text representation of this object to the given output stream. More...
 
void regina::ModelLinkGraphCells::writeTextLong (std::ostream &out) const
 Writes a detailed text representation of this object to the given output stream. More...
 
ModelLinkGraphCellsregina::ModelLinkGraphCells::operator= (const ModelLinkGraphCells &)=delete
 
 regina::XMLLinkReader::XMLLinkReader (XMLTreeResolver &resolver)
 Creates a new knot/link reader. More...
 
virtual Packetregina::XMLLinkReader::packet () override
 Returns the newly allocated packet that has been read by this element reader. More...
 
virtual XMLElementReaderregina::XMLLinkReader::startContentSubElement (const std::string &subTagName, const regina::xml::XMLPropertyDict &subTagProps) override
 Used instead of startSubElement() for XML subelements that are not child packets or packet tags. More...
 
virtual void regina::XMLLinkReader::endContentSubElement (const std::string &subTagName, XMLElementReader *subReader) override
 Used instead of endSubElement() for XML subelements that are not child packets or packet tags. More...
 
 regina::XMLLinkCrossingsReader::XMLLinkCrossingsReader (Link *link)
 Creates a new crossings reader. More...
 
virtual void regina::XMLLinkCrossingsReader::startElement (const std::string &, const regina::xml::XMLPropertyDict &, XMLElementReader *) override
 Signifies that parsing of this XML element is beginning. More...
 
virtual void regina::XMLLinkCrossingsReader::initialChars (const std::string &chars) override
 Signifies that the initial text belonging to this XML element has been read. More...
 
bool regina::XMLLinkCrossingsReader::broken () const
 Indicates whether the XML element has been found to contain invalid data. More...
 
 regina::XMLLinkConnectionsReader::XMLLinkConnectionsReader (Link *link)
 Creates a new connections reader. More...
 
virtual void regina::XMLLinkConnectionsReader::initialChars (const std::string &chars)
 Signifies that the initial text belonging to this XML element has been read. More...
 
bool regina::XMLLinkConnectionsReader::broken () const
 Indicates whether the XML element has been found to contain invalid data. More...
 
 regina::XMLLinkComponentsReader::XMLLinkComponentsReader (Link *link)
 Creates a new components reader. More...
 
virtual void regina::XMLLinkComponentsReader::startElement (const std::string &, const regina::xml::XMLPropertyDict &, XMLElementReader *)
 Signifies that parsing of this XML element is beginning. More...
 
virtual void regina::XMLLinkComponentsReader::initialChars (const std::string &chars)
 Signifies that the initial text belonging to this XML element has been read. More...
 
bool regina::XMLLinkComponentsReader::broken () const
 Indicates whether the XML element has been found to contain invalid data. More...
 

Variables

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

Friends

class regina::StrandRef::Link
 
class regina::StrandRef::ModelLinkGraph
 
class regina::StrandRef::Tangle
 
class regina::Crossing::Link
 
class regina::Crossing::ModelLinkGraph
 
class regina::Crossing::Tangle
 
class regina::Crossing::XMLLinkCrossingsReader
 
class regina::Crossing::XMLLinkConnectionsReader
 
class regina::ModelLinkGraphArc::ModelLinkGraph
 
class regina::ModelLinkGraphNode::ModelLinkGraph
 
class regina::ModelLinkGraphCells::ModelLinkGraph
 

Building Links

class regina::Link::ModelLinkGraph
 
class regina::Link::Tangle
 
class regina::Link::XMLLinkCrossingsReader
 
class regina::Link::XMLLinkComponentsReader
 
void regina::Link::insertTorusLink (int p, int q, bool positive=true)
 Inserts a new (p, q) torus link into this link. More...
 
template<typename... Args>
static Linkregina::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 Linkregina::Link::fromKnotSig (const std::string &sig)
 Recovers a knot diagram from its signature. More...
 
static Linkregina::Link::fromGauss (const std::string &str)
 Creates a new knot from a classical Gauss code. More...
 
template<typename Iterator >
static Linkregina::Link::fromGauss (Iterator begin, Iterator end)
 Creates a new knot from a classical Gauss code. More...
 
static Linkregina::Link::fromOrientedGauss (const std::string &str)
 Creates a new knot from an "oriented" variant of the Gauss code. More...
 
template<typename Iterator >
static Linkregina::Link::fromOrientedGauss (Iterator begin, Iterator end)
 Creates a new knot from an "oriented" variant of the Gauss code. More...
 
static Linkregina::Link::fromJenkins (const std::string &str)
 Builds a link from the text representation described by Bob Jenkins. More...
 
static Linkregina::Link::fromJenkins (std::istream &in)
 Builds a link from the text representation described by Bob Jenkins. More...
 
static Linkregina::Link::fromDT (const std::string &str)
 Creates a new knot from either alphabetical or numerical Dowker-Thistlethwaite notation. More...
 
template<typename Iterator >
static Linkregina::Link::fromDT (Iterator begin, Iterator end)
 Creates a new knot from an integer sequence using the numerical variant of Dowker-Thistlethwaite notation. More...
 
static XMLPacketReaderregina::Link::xmlReader (Packet *parent, XMLTreeResolver &resolver)
 
virtual Packetregina::Link::internalClonePacket (Packet *parent) const override
 Makes a newly allocated copy of this packet. More...
 
virtual void regina::Link::writeXMLPacketData (std::ostream &out) const override
 Writes a chunk of XML containing the data for this packet only. More...
 

Constructors and Destructors

 regina::Link::Link ()
 Constructs an empty link. More...
 
 regina::Link::Link (size_t unknots)
 Constructs the unlink with the given number of components. More...
 
 regina::Link::Link (const Link &copy)
 Constructs a new copy of the given link. More...
 
 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. More...
 
 regina::Link::Link (const std::string &description)
 "Magic" constructor that tries to find some way to interpret the given string as a link. More...
 
 regina::Link::~Link ()
 Destroys this link. More...
 

Crossings and Components

bool regina::Link::isEmpty () const
 Determines whether this link is empty. More...
 
size_t regina::Link::size () const
 Returns the number of crossings in this link. More...
 
size_t regina::Link::countComponents () const
 Returns the number of components in this link. More...
 
Crossingregina::Link::crossing (size_t index) const
 Returns a pointer to the crossing at the given index within this link. More...
 
StrandRef regina::Link::component (size_t index) const
 Returns a strand in the given component of this link. More...
 
StrandRef regina::Link::strand (int id) const
 Returns the strand in the link with the given integer ID. More...
 
StrandRef regina::Link::translate (const StrandRef &other) const
 Translates a strand reference for some other link into the corresponding strand reference for this link. More...
 
bool regina::Link::connected (const Crossing *a, const Crossing *b) const
 Determines whether the two given crossings are connected in the underlying 4-valent graph of the link diagram. More...
 

Editing

void regina::Link::swapContents (Link &other)
 Swaps the contents of this and the given link. More...
 
void regina::Link::change (Crossing *c)
 Switches the upper and lower strands of the given crossing. More...
 
void regina::Link::changeAll ()
 Switches the upper and lower strands of every crossing in the diagram. More...
 
void regina::Link::resolve (Crossing *c)
 Resolves the given crossing. More...
 
void regina::Link::reflect ()
 Converts this link into its reflection. More...
 
void regina::Link::rotate ()
 Rotates this link diagram, converting it into a different diagram of the same link. More...
 
void regina::Link::reverse ()
 Reverses the orientation of every component of this link. More...
 
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. More...
 
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. More...
 
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. More...
 
bool regina::Link::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 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. More...
 
bool regina::Link::r3 (StrandRef arc, int side, bool check=true, bool perform=true)
 Tests for and/or performs a type III Reidemeister move. More...
 
bool regina::Link::r3 (Crossing *crossing, int side, bool check=true, bool perform=true)
 Tests for and/or performs a type III Reidemeister move. More...
 
bool regina::Link::hasReducingPass () const
 Tests whether this knot has a pass move that will reduce the number of crossings. More...
 
bool regina::Link::intelligentSimplify ()
 Attempts to simplify the link diagram using fast and greedy heuristics. More...
 
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. More...
 
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. More...
 
template<typename Action , typename... Args>
bool regina::Link::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 regina::Link::composeWith (const Link &other)
 Forms the composition of this with the given link. More...
 

Invariants and Related Properties

bool regina::Link::isAlternating () const
 Returns whether this knot diagram is alternating. More...
 
long regina::Link::linking () const
 Returns the linking number of this link. More...
 
long regina::Link::writhe () const
 Returns the writhe of this link diagram. More...
 
Triangulation< 3 > * regina::Link::complement (bool simplify=true) const
 Returns an ideal triangulation of the complement of this link in the 3-sphere. More...
 
Linkregina::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 > & regina::Link::bracket (Algorithm alg=ALG_DEFAULT, ProgressTracker *tracker=nullptr) const
 Returns the Kauffman bracket polynomial of this link diagram. More...
 
bool regina::Link::knowsBracket () const
 Is the Kauffman bracket polynomial of this link diagram already known? See bracket() for further details. More...
 
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. More...
 
bool regina::Link::knowsJones () const
 Is the Jones polynomial of this link diagram already known? See jones() for further details. More...
 
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. More...
 
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. More...
 
const Laurent2< Integer > & regina::Link::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 regina::Link::knowsHomfly () const
 Is the HOMFLY polynomial of this link diagram already known? See homflyAZ() and homflyLM() for further details. More...
 
const TreeDecompositionregina::Link::niceTreeDecomposition () const
 Returns a nice tree decomposition of the planar 4-valent multigraph formed by this link diagram. More...
 
void regina::Link::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 regina::Link::writeTextShort (std::ostream &out) const override
 Writes a short text representation of this object to the given output stream. More...
 
virtual void regina::Link::writeTextLong (std::ostream &out) const override
 Writes a detailed text representation of this object to the given output stream. More...
 
virtual bool regina::Link::dependsOnParent () const override
 Determines if this packet depends upon its parent. More...
 

Exporting Links

std::string regina::Link::brief () const
 Outputs this link in Regina's own brief format. More...
 
std::string regina::Link::gauss () const
 Outputs a classical Gauss code for this knot. More...
 
void regina::Link::gauss (std::ostream &out) const
 Writes a classical Gauss code for this knot to the given output stream. More...
 
std::string regina::Link::orientedGauss () const
 Outputs an oriented Gauss code for this knot. More...
 
void regina::Link::orientedGauss (std::ostream &out) const
 Writes an oriented Gauss code for this knot to the given output stream. More...
 
std::string regina::Link::jenkins () const
 Exports this link as a string using the text representation described by Bob Jenkins. More...
 
void regina::Link::jenkins (std::ostream &out) const
 Exports this link to the given output stream using the text representation described by Bob Jenkins. More...
 
std::string regina::Link::dt (bool alpha=false) const
 Outputs this knot using Dowker-Thistlethwaite notation. More...
 
void regina::Link::dt (std::ostream &out, bool alpha=false) const
 Writes this knot to the given output stream using Dowker-Thistlethwaite notation. More...
 
void regina::Link::writePACE (std::ostream &out) const
 Outputs the underlying planar 4-valent multigraph using the PACE text format. More...
 
std::string regina::Link::pace () const
 Returns a text representation of the underlying planar 4-valent multigraph, using the PACE text format. More...
 
std::string regina::Link::dumpConstruction () const
 Returns C++ code that can be used to reconstruct this link. More...
 
std::string regina::Link::knotSig (bool useReflection=true, bool useReversal=true) const
 Constructs the signature for this knot diagram. More...
 

Constructors and Destructors

 regina::Tangle::Tangle ()
 Constructs the zero tangle. More...
 
 regina::Tangle::Tangle (int twists)
 Constructs a tangle from the given number of twists. More...
 
 regina::Tangle::Tangle (int num, int den)
 Constructs a rational tangle with the given parameters. More...
 
 regina::Tangle::Tangle (const Link &knot)
 Creates a tangle from two parallel copies of the given knot. More...
 
 regina::Tangle::Tangle (const Tangle &copy)
 Constructs a new copy of the given tangle. More...
 
 regina::Tangle::~Tangle ()
 Destroys this tangle. More...
 

Crossings and Strings

char regina::Tangle::type () const
 Returns the type of this tangle. More...
 
size_t regina::Tangle::size () const
 Returns the number of crossings in this tangle. More...
 
Crossingregina::Tangle::crossing (size_t index) const
 Returns a pointer to the crossing at the given index within this tangle. More...
 
StrandRef regina::Tangle::begin (int string) const
 Returns the crossing closest to the beginning of the given string. More...
 
StrandRef regina::Tangle::end (int string) const
 Returns the crossing closest to the end of the given string. More...
 
StrandRef regina::Tangle::translate (const StrandRef &other) const
 Translates a strand reference for some other tangle into the corresponding strand reference for this tangle. More...
 

Editing

void regina::Tangle::swapContents (Tangle &other)
 Swaps the contents of this and the given tangle. More...
 
void regina::Tangle::twist (int sign=1)
 Adds a twist to the right-hand end of this tangle. More...
 
void regina::Tangle::turn (int direction=1)
 Rotates this tangle by 90 degrees. More...
 
void regina::Tangle::changeAll ()
 Switches the upper and lower strands of every crossing in the tangle. More...
 
bool regina::Tangle::r1 (Crossing *crossing, bool check=true, bool perform=true)
 Tests for and/or performs a type I Reidemeister move to remove a crossing. More...
 
bool regina::Tangle::r2 (StrandRef arc, bool check=true, bool perform=true)
 Tests for and/or performs a type II Reidemeister move to remove two crossings. More...
 
bool regina::Tangle::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 regina::Tangle::simplifyToLocalMinimum (bool perform=true)
 Uses type I and II Reidemeister moves to reduce the tangle monotonically to some local minimum number of crossings. More...
 

Algebra on Tangles

void regina::Tangle::add (const Tangle &other)
 Adds the given tangle to the right-hand side of this tangle. More...
 
void regina::Tangle::negate ()
 Reflects this tangle through the diagonal axis running from the top-left to bottom-right corners of the diagram. More...
 
void regina::Tangle::box (const Tangle &topLeft, const Tangle &topRight, const Tangle &bottomLeft, const Tangle &bottomRight)
 Encloses this tangle with the four given tangles in a box configuration. More...
 
Linkregina::Tangle::numClosure () const
 Forms the numerator closure of this tangle. More...
 
Linkregina::Tangle::denClosure () const
 Forms the denominator closure of this tangle. More...
 

Output

void regina::Tangle::writeTextShort (std::ostream &out) const
 Writes a short text representation of this tangle to the given output stream. More...
 
void regina::Tangle::writeTextLong (std::ostream &out) const
 Writes a detailed text representation of this tangle to the given output stream. More...
 

Exporting Tangles

std::string regina::Tangle::orientedGauss () const
 Outputs an oriented Gauss code for this tangle. More...
 
void regina::Tangle::orientedGauss (std::ostream &out) const
 Writes an oriented Gauss code for this tangle to the given output stream. More...
 

Building Tangles

static Tangleregina::Tangle::fromOrientedGauss (const std::string &str)
 Creates a new tangle from an oriented Gauss code. More...
 
template<typename Iterator >
static Tangleregina::Tangle::fromOrientedGauss (Iterator begin, Iterator end)
 Creates a new tangle from an oriented Gauss code. More...
 
Tangleregina::Tangle::operator= (const Tangle &)=delete
 

Detailed Description

Knots and links in the 3-sphere.

Typedef Documentation

◆ Use

typedef void(* regina::ModelLinkGraph::Use) (Link *, void *)

A routine that can do arbitrary processing upon a knot or link.

Such routines are used to process links that are found when running generateMinimalLinks().

The first parameter passed should be a link, which must be deallocated by this routine. The second parameter may contain arbitrary data as passed to generateMinimalLinks().

Note that the first parameter might be null to signal that link generation has finished.

Warning
The API for this class has not yet been finalised. This means that the class interface may change in new versions of Regina, without maintaining backward compatibility. If you use this class directly in your own code, please watch the detailed changelogs upon new releases to see if you need to make changes to your code.

Enumeration Type Documentation

◆ Framing

Indicates one of the standard framings of a knot or link.

Here a framing refers to a choice of normal vector field along the knot or link. Equivalently, a framing refers to a choice of longitude on the torus bounding each component of the link.

Enumerator
FRAMING_SEIFERT 

Indicates the Seifert framing, which is defined algebraically and is independent of the knot/link projection.

For each component of the link, draw a Seifert surface (i.e., an orientable surface embedded in the 3-sphere that is bounded by the corresponding knot). The Seifert framing is the vector field that points into the corresponding surface.

Equivalently, for each component of the link, the Seifert framing chooses the unique longitude for the corresponding knot that is trivial in the homology of the knot complement.

FRAMING_BLACKBOARD 

Indicates the blackboard framing, which is specific to the knot/link projection.

For the blackboard framing, the normal vector field stays within the projection plane. Equivalently, the blackboard framing chooses longitudes whose projections do not intersect the original link diagram.

Function Documentation

◆ add()

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

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

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

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

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

It is allowed to pass this tangle as other.

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

◆ adj()

const ModelLinkGraphArc & regina::ModelLinkGraphNode::adj ( int  which) const
inline

Returns the arc at the other end of the given graph edge that exits this node.

Let e be the undirected edge of the underlying model graph that corresponds to the given outgoing arc from this node. Recall that there are two ModelLinkGraphArc objects corresponding to e, one for each of its endpoints. One of these will be ModelLinkGraphArc(this, which); this routine returns the other object, which is the ModelLinkGraphArc describing the other endpoint of e.

Note that for a node n, calling n.adj(i) is equivalent to calling n.arc(i).traverse().

Parameters
whichan integer in the range 0 to 3 inclusive, indicating which of the four arcs exiting this node we should examine.
Returns
a reference to the other end of the same undirected edge of the underlying model graph.

◆ arc() [1/3]

int regina::ModelLinkGraphArc::arc ( ) const
inline

Indicates which arc this is amongst the four arcs exiting the underlying node of the model graph.

For each node of a model graph, the four arcs exiting that node are numbered 0,1,2,3 in a clockwise order.

Returns
an integer between 0 and 3 inclusive indicating one of the four arcs exiting node().

◆ arc() [2/3]

ModelLinkGraphArc regina::ModelLinkGraphNode::arc ( int  which)
inline

Returns a reference to one of the four arcs of the graph that exit this node.

This is equivalent to directly constructing ModelLinkGraphArc(this, which).

The four arcs exiting this node are numbered 0,1,2,3 in a clockwise order around the node.

Parameters
whichan integer in the range 0 to 3 inclusive, indicating which of the four arcs exiting this node we should return.
Returns
a reference to the corresponding arc exiting this node.

◆ arc() [3/3]

const ModelLinkGraphArc & regina::ModelLinkGraphCells::arc ( size_t  cell,
size_t  which 
) const
inline

Returns the given arc along the boundary of the given 2-cell.

For each cell, the arcs along the boundary are given in order as you walk anticlockwise around the cell (so the cell is on the left of each arc as you walk around the cell boundary).

Each arc is described in the form of an outgoing arc from some node of the underlying graph (so if the return ModelLinkGraphArc is a then this describes an outgoing arc from a.node()). It follows that, if the underlying graph has n nodes, then each of the 4n possible ModelLinkGraphArc values appears exactly once as arc(cell, which) for some integers cell and which.

Precondition
The underlying ModelLinkGraph is non-empty, connected, and describes a planar graph embedding. Note that connectivity is already required by the class constructor, and you can test the remaining conditions by calling isValid().
Parameters
cellindicates which cell to query; this must be between 0 and countCells()-1 inclusive.
whichindicates which arc along the boundary of the corresponding cell to return; this must be between 0 and size(cell)-1 inclusive.
Returns
the requested arc on the boundary of the given 2-cell.

◆ ArcIterator() [1/3]

regina::ArcIterator::ArcIterator ( )
inline

Creates a singular iterator.

◆ ArcIterator() [2/3]

regina::ArcIterator::ArcIterator ( const ArcIterator )
default

Default copy constructor.

◆ ArcIterator() [3/3]

regina::ArcIterator::ArcIterator ( const Link link,
size_t  crossing = 0,
bool  upper = false 
)
inline

Creates a new iterator pointing to the arc exiting the given strand of the given crossing of the given link.

Parameters
linkthe underlying knot/link.
crossingthe index of the given crossing. This must be between 0 and link.size()-1 for a deferencable iterator, or must be exactly link.size() for a past-the-end iterator.
uppertrue or false according to whether the iterator should point to the arc exiting the given crossing from the upper or lower strand respectively. For a past-the-end iterator, this should always be false.

◆ begin() [1/2]

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

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

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

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

◆ begin() [2/2]

const ModelLinkGraphArc * regina::ModelLinkGraphCells::begin ( size_t  cell) const
inline

Returns the beginning of an iterator range for walking around the boundary of the given 2-cell.

Suppose that the ith cell is a k-gon. Then the iterator range described by begin(i) and end(i) will iterate through the k arcs along the boundary of the ith cell in the same order as described by arc(); that is, walking anticlockwise around the cell boundary with the cell to the left of each arc.

Dereferencing the jth iterator in this range gives the same result as calling arc(cell, j).

Precondition
The underlying ModelLinkGraph is non-empty, connected, and describes a planar graph embedding. Note that connectivity is already required by the class constructor, and you can test the remaining conditions by calling isValid().
Python
Not present. Use arc() and size() instead.
Returns
the beginning of an iterator range for the boundary of the given cell.

◆ borromean()

static Link* regina::ExampleLink::borromean ( )
static

Returns a six-crossing diagram of the Borromean rings.

Returns
a newly constructed link, which must be destroyed by the caller of this routine.

◆ box()

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

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

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

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

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

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

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

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

◆ bracket()

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

Returns the Kauffman bracket polynomial of this link diagram.

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

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

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

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

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

◆ brief()

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

Outputs this link in Regina's own brief format.

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

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

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

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

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

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

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

The string will not end in a newline.

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

◆ broken() [1/3]

bool regina::XMLLinkCrossingsReader::broken ( ) const

Indicates whether the XML element has been found to contain invalid data.

Returns
true if and only if invalid data has been found.

◆ broken() [2/3]

bool regina::XMLLinkConnectionsReader::broken ( ) const

Indicates whether the XML element has been found to contain invalid data.

Returns
true if and only if invalid data has been found.

◆ broken() [3/3]

bool regina::XMLLinkComponentsReader::broken ( ) const

Indicates whether the XML element has been found to contain invalid data.

Returns
true if and only if invalid data has been found.

◆ canonicalPlantri()

std::string regina::ModelLinkGraph::canonicalPlantri ( bool  useReflection = true,
bool  tight = false 
) const

Outputs a text representation of this graph in the plantri ASCII format, using a canonical relabelling of nodes and arcs, and with optional compression.

This routine is similar to plantri(), but with two significant differences:

  • This routine does not preserve the labelling of nodes and the order of arcs around each node. Instead it reorders the nodes and arcs so that any two relabellings of the "same" planar embedding will produce the same canonicalPlantri() output. By "same" we allow for relabelling and isotopy (sliding the graph around the sphere); if the argument useReflection is true then we allow for reflection also.
  • If the argument tight is true, then this routine uses an abbreviated output format. The resulting compression is only trivial (it reduces the length by roughly 40%), but the resulting string is still human-parseable (though with a little more effort required). This compression will simply remove the commas, and for each node it will suppress the destination of the first arc (since this can be deduced from the canonical labelling).

Regardless of whether tight is true or false, the resulting string can be parsed by fromPlantri() to reconstruct the original graph. Note however that, due to the canonical labelling, the resulting graph might be a relabelling of the original (and might even be a reflection of the original, if useReflection was passed as true).

See plantri() for further details on the ASCII format itself.

The running time for this routine is quadratic in the size of the graph.

Precondition
This graph is connected.
This graph has between 1 and 26 nodes inclusive.
The dual to this graph is a simple quadrangulation of the sphere. In particular, the dual must not have any parallel edges. Note that any graph that fails this condition will the model graph for a link diagram that is an "obvious" connected sum.
Parameters
useReflectiontrue if a graph and its reflection should be considered the same (i.e., produce the same canonical output), or false if they should be considered different. Of course, if a graph is symmetric under reflection then the graph and its reflection will produce the same canonical output regardless of this parameter.
tightfalse if the usual plantri ASCII format should be used (as described by plantri() and fromPlantri()), or true if the abbreviated format should be used as described above.
Returns
an optionally compressed plantri ASCII representation of this graph.

◆ cell()

size_t regina::ModelLinkGraphCells::cell ( const ModelLinkGraphArc arc) const
inline

Returns the 2-cell that lies to the left of the given arc.

Specifically, this function returns the number of the cell that lies to the left of the given arc as you walk along it away from arc.node().

For any arc a, calling arc(cell(a), cellPos(a)) will return the same arc a again.

Precondition
The underlying ModelLinkGraph is non-empty, connected, and describes a planar graph embedding. Note that connectivity is already required by the class constructor, and you can test the remaining conditions by calling isValid().
Parameters
arcthe given arc of the underlying graph.
Returns
the number of the cell that lies to the left of the given arc; this will be an integer between 0 and countCells()-1 inclusive.

◆ cellPos()

size_t regina::ModelLinkGraphCells::cellPos ( const ModelLinkGraphArc arc) const
inline

Returns where the given arc appears along the boundary of the 2-cell to its left.

Consider the cell c to the left of the given arc as you follow the arc away from arc.node(). The routine arc() can be used to enumerate the sequence of arcs along the boundary of this cell c, in order as you walk anticlockwise around the cell boundary. The purpose of this routine is to identify where in this sequence the given arc occurs.

For any arc a, calling arc(cell(a), cellPos(a)) will return the same arc a again.

Precondition
The underlying ModelLinkGraph is non-empty, connected, and describes a planar graph embedding. Note that connectivity is already required by the class constructor, and you can test the remaining conditions by calling isValid().
Parameters
arcthe given arc of the underlying graph.
Returns
the position of the given arc on the boundary of the cell to its left; this will be an integer between 0 and size(cell(arc))-1 inclusive.

◆ cells()

const ModelLinkGraphCells & regina::ModelLinkGraph::cells ( ) const
inline

Returns details of the cellular decomposition of the sphere that is induced by this graph.

This cellular decomposition will only be computed on demand. This means that the first call to this function will take linear time (as the decomposition is computed), but subsequent calls will be constant time (since the decomposition is cached).

Precondition
This graph is connected.
Returns
the induced cellular decomposition of the sphere.

◆ change()

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

Switches the upper and lower strands of the given crossing.

Parameters
cthe crossing to change.

◆ changeAll() [1/2]

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.

◆ changeAll() [2/2]

void regina::Tangle::changeAll ( )

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

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

◆ complement()

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

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

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

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

What happens next depends upon the argument simplify:

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

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

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

◆ component()

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

Returns a strand in the given component of this link.

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

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

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

◆ composeWith()

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

Forms the composition of this with the given link.

This link will be altered directly.

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

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

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

It is allowed to pass this link as other.

Parameters
otherthe link with which this should be composed.

◆ connected()

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

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

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

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

◆ conway()

static Link* regina::ExampleLink::conway ( )
static

Returns the 11-crossing Conway knot.

This is the reflection of K11n34 in the Knot Atlas, and is a mutant of the Kinoshita-Terasaka knot.

Returns
a newly constructed link, which must be destroyed by the caller of this routine.

◆ countCells()

size_t regina::ModelLinkGraphCells::countCells ( ) const
inline

Returns the number of 2-cells in this cellular decomposition.

If isValid() returns false (i.e., the underlying ModelLinkGraph is either empty or does not describe a planar embedding), then this routine will return 0 instead. Note that this routine cannot be used to test for connectivity, which is a non-negotiable precondition required by the class constructor.

Note that, if isValid() returns true, then countCells() will always return n+2 where n is the number of nodes in the underlying graph.

Returns
a strictly positive number of 2-cells if isValid() returns true, or 0 if isValid() returns false.

◆ countComponents()

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

Returns the number of components in this link.

Returns
the number of components.

◆ crossing() [1/3]

Crossing * regina::StrandRef::crossing ( ) const
inline

The crossing that this reference points to.

The information returned by crossing() and strand() together pinpoint exactly which strand of the link this reference points to.

Returns
the crossing, or null if this is a null reference.

◆ crossing() [2/3]

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

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

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

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

◆ crossing() [3/3]

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

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

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

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

◆ CrossingIterator() [1/3]

regina::CrossingIterator::CrossingIterator ( )
inline

Creates a singular iterator.

◆ CrossingIterator() [2/3]

regina::CrossingIterator::CrossingIterator ( const CrossingIterator )
default

Default copy constructor.

◆ CrossingIterator() [3/3]

regina::CrossingIterator::CrossingIterator ( const Link link,
size_t  index = 0 
)
inline

Creates a new iterator pointing to the given crossing of the given link.

Parameters
linkthe underlying knot/link.
indexthe index of the crossing to point to. This must be between 0 and link.size()-1 for a deferencable iterator, or must be exactly link.size() for a past-the-end iterator.

◆ denClosure()

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

Forms the denominator closure of this tangle.

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

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

◆ dependsOnParent()

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

Determines if this packet depends upon its parent.

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

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

Implements regina::Packet.

◆ dt() [1/2]

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

Outputs this knot using Dowker-Thistlethwaite notation.

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

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

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

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

The string will not contain any newlines.

Note
There is another variant of this routine that, instead of returning a string, writes directly to an output stream.
Parameters
alphatrue to use alphabetical notation, or false (the default) to use numerical notation.
Returns
the Dowker-Thistlethwaite notation for this knot diagram. This routine will return the empty string if this link has zero or multiple components, or if alpha is true and the knot has more than 26 crossings.

◆ dt() [2/2]

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

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

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

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

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

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

The output will not contain any newlines.

Note
There is another variant of this routine that, instead of using an output stream, simply returns a string.
Python
This routine is not available in Python. Instead, Python users can use the variant dt(), which takes just the optional alpha argument and returns the output as a string.
Parameters
outthe output stream to which to write.
alphatrue to use alphabetical notation, or false (the default) to use numerical notation.

◆ dumpConstruction()

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

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

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

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

Returns
the C++ code that was generated.

◆ end() [1/2]

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

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

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

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

◆ end() [2/2]

const ModelLinkGraphArc * regina::ModelLinkGraphCells::end ( size_t  cell) const
inline

Returns the end of an iterator range for walking around the boundary of the given 2-cell.

As is usual for iterator ranges, this is a past-the-end value (i.e., this iterator cannot be dereferenced).

Suppose that the ith cell is a k-gon. Then the iterator range described by begin(i) and end(i) will iterate through the k arcs along the boundary of the ith cell in the same order as described by arc(); that is, walking anticlockwise around the cell boundary with the cell to the left of each arc.

Dereferencing the jth iterator in this range gives the same result as calling arc(cell, j).

Precondition
The underlying ModelLinkGraph is non-empty, connected, and describes a planar graph embedding. Note that connectivity is already required by the class constructor, and you can test the remaining conditions by calling isValid().
Python
Not present. Use arc() and size() instead.
Returns
the end of an iterator range for the boundary of the given cell.

◆ endContentSubElement()

void regina::XMLLinkReader::endContentSubElement ( const std::string &  subTagName,
XMLElementReader subReader 
)
inlineoverridevirtual

Used instead of endSubElement() for XML subelements that are not child packets or packet tags.

The default implementation does nothing.

Parameters
subTagNamethe name of the subelement closing tag.
subReaderthe child reader that was used to parse the subelement (this is the reader that was returned by the corresponding startContentSubElement() call). It is guaranteed that endElement() has already been called upon this child reader and that the child reader has not yet been destroyed.

Reimplemented from regina::XMLPacketReader.

◆ figureEight()

static Link* regina::ExampleLink::figureEight ( )
static

Returns a four-crossing diagram of the figure eight knot.

Returns
a newly constructed link, which must be destroyed by the caller of this routine.

◆ findFlype()

std::pair<ModelLinkGraphArc, ModelLinkGraphArc> regina::ModelLinkGraph::findFlype ( const ModelLinkGraphArc from) const

TODO: Flype is between arc– and arc, i.e., over the region defined by cell(arc).

Returns (null, null) iff flype() will refuse to work with this. Otherwise returns (left outgoing arc, right outgoing arc).

Conditions that explicitly return null:

  • The upper and lower cells are the same.
  • The common cell is the inside cell at from.node().
Precondition
This graph is connected and TODO: valid.
Python
Instead of a C++ pair, this routine returns a Python tuple containing two ModelLinkGraphArc objects.

◆ flype() [1/2]

ModelLinkGraph * regina::ModelLinkGraph::flype ( const ModelLinkGraphArc from) const
inline

TODO: Document.

◆ flype() [2/2]

ModelLinkGraph* regina::ModelLinkGraph::flype ( const ModelLinkGraphArc from,
const ModelLinkGraphArc left,
const ModelLinkGraphArc right 
) const

TODO: Document.

       Cell A

    __   __
      \ /                    ----> left
       X         Cell B
    __/ \__from              ----> right

       Cell C

Conditions that explicitly return 0:

  • Neither left nor right ends at from.node().
  • The upper and lower bounding cells are distinct,
  • The cell between left and right is not the inside cell where the flype begins from from.node().

◆ fromData()

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

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

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

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

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

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

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

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

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

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

◆ fromDT() [1/2]

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

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

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

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

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

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

4 6 2
bca

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

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

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

◆ fromDT() [2/2]

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

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

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

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

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

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

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

◆ fromGauss() [1/2]

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

Creates a new knot from a classical Gauss code.

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

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

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

The format works as follows:

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

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

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

1 -2 3 -1 2 -3

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

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

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

◆ fromGauss() [2/2]

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

Creates a new knot from a classical Gauss code.

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

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

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

◆ fromJenkins() [1/2]

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

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

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

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

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

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

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

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

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

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

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

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

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

◆ fromJenkins() [2/2]

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

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

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

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

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

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

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

◆ fromKnotSig()

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

Recovers a knot diagram from its signature.

See knotSig() for more information on knot signatures.

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

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

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

◆ fromOrientedGauss() [1/4]

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

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

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

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

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

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

The format works as follows:

  • Label the crossings arbitrarily as 1, 2, ..., n.
  • Start at some point on the knot and follow it around. At every crossing that you pass, write a token of the form +<k, -<k, +>k or ->k, where:
    • the symbol + indicates that you are passing over the crossing labelled k, and the symbol - indicates that you are passing under the crossing labelled k;
    • the symbol < indicates that the other strand of the crossing passes from right to left, and > indicates that the other strand passes from left to right.

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

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

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

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

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

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

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

◆ fromOrientedGauss() [2/4]

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

Creates a new tangle from an oriented Gauss code.

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

The format works as follows:

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

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

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

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

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

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

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

◆ fromOrientedGauss() [3/4]

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

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

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

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

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

Precondition
Iterator is a random access iterator type.
Dereferencing such an iterator produces either a C-style string (which can be cast to const char*) or a C++-style string (which can be cast to const std::string&).
The tokens in the input sequence do not contain any whitespace.
Warning
While this routine does some error checking on the input, it does not test for planarity of the diagram. That is, if the input describes a knot diagram that must be drawn on some higher-genus surface as opposed to the plane, this will not be detected. Of course such inputs are not allowed, and it is currently up to the user to enforce this.
Python
Instead of a pair of begin and past-the-end iterators, this routine takes a Python list of strings.
Parameters
beginan iterator that points to the beginning of the sequence of tokens for an "oriented" Gauss code.
endan iterator that points past the end of the sequence of tokens for an "oriented" Gauss code.
Returns
a newly constructed link, or null if the input was found to be invalid.

◆ fromOrientedGauss() [4/4]

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

Creates a new tangle from an oriented Gauss code.

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

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

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

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

◆ fromPlantri()

static ModelLinkGraph* regina::ModelLinkGraph::fromPlantri ( const std::string &  plantri)
static

Builds a graph from a line of plantri output.

The software plantri, by Gunnar Brinkmann and Brendan McKay, can be used to enumerate 4-valent planar graphs (amongst many other things). This routine converts a piece of output from plantri into a ModelLinkGraph object that Regina can work with directly.

The output from plantri must be in ASCII format, and must be the dual graph of a simple quadrangulation of the sphere. The corresponding flags that must be passed to plantri to obtain such output are -adq (although you will may wish to pass additional flags to expand or restrict the classes of graphs that plantri builds).

When run with these flags, plantri produces output in the following form:

6 bbcd,adca,abee,affb,cffc,deed
6 bcdd,aeec,abfd,acfa,bffb,ceed
6 bcde,affc,abfd,acee,addf,becb

Each line consists of an integer (the number of nodes in the graph), followed by a comma-separated sequence of alphabetical strings that encode the edges leaving each node.

This function only takes the comma-separated sequence of alphabetical strings. So, for example, to construct the graph correpsonding to the second line of output above, you could call:

fromPlantri("bcdd,aeec,abfd,acfa,bffb,ceed");

Regina can only recognise graphs in this format with up to 26 nodes. If the graph contains more than 27 nodes then the plantri output will contain punctuation, Regina will not be able to parse it, and this function will return null.

The given string does not need to be come from the program plantri itself. Whereas plantri always outputs graphs with a particular canonical labelling, this function can accept an arbitrary ordering of nodes and arcs - in particular, it can accept the string g.plantri() for any graph g that meets the preconditions below. Nevertheless, the graph must still meet these preconditions, since otherwise the plantri format might not be enough to uniquely reconstruct the graph and its planar embedding.

This routine can also interpret the "tight" format that is output by the member function canonicalPlantri() (even though such output would certainly not be produced by the program plantri).

Warning
While this routine does some error checking on the input, it does not test for planarity of the graph. Of course plantri does not output non-planar graphs, but if a user constructs one by hand and passes it to this routine then the resulting behaviour is undefined.
Precondition
The graph being described is connected.
The graph being described has between 1 and 26 nodes inclusive.
The graph being described is dual to a simple quadrangulation of the sphere. In particular, the dual must not have any parallel edges. Note that any graph that fails this condition will the model graph for a link diagram that is an "obvious" connected sum.
Parameters
plantria string containing the comma-separated sequence of alphabetical strings output by plantri, as described above.
Returns
a newly constructed graph, or null if the input was found to be invalid.

◆ gauss() [1/2]

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

Outputs a classical Gauss code for this knot.

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

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

The string will not contain any newlines.

Note
There is another variant of this routine that, instead of returning a string, writes directly to an output stream.
Returns
a classical Gauss code for this knot, or the empty string if this is a link with zero or multiple components.

◆ gauss() [2/2]

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

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

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

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

The output will not contain any newlines.

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

◆ generateMinimalLinks()

void regina::ModelLinkGraph::generateMinimalLinks ( Use  use,
void *  useArgs = 0 
) const

TODO: Document.

Only aims for minimal, ignores reflections.

Node n will become crossing n.

Arc (0,0) will always be forwards, and crossing 0 will always be positive.

TODO: PRE: Knot, not link.

Warning
The API for this class has not yet been finalised. This means that the class interface may change in new versions of Regina, without maintaining backward compatibility. If you use this class directly in your own code, please watch the detailed changelogs upon new releases to see if you need to make changes to your code.

◆ gordian()

static Link* regina::ExampleLink::gordian ( )
static

Returns Haken's Gordian unknot, a 141-crossing diagram of the unknot that is difficult to untangle.

Returns
a newly constructed link, which must be destroyed by the caller of this routine.

◆ gst()

static Link* regina::ExampleLink::gst ( )
static

Returns a 48-crossing potential counterexample to the slice-ribbon conjecture, as described by Gompf, Scharlemann and Thompson.

Specifically, this knot is Figure 2 from their paper "Fibered knots and potential counterexamples to the property 2R and slice-ribbon conjectures", arXiv:1103.1601.

Returns
a newly constructed link, which must be destroyed by the caller of this routine.

◆ hasReducingPass()

bool regina::Link::hasReducingPass ( ) const

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

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

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

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

The running time is cubic in the number of crossings.

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

◆ homfly()

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

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

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

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

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

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

◆ homflyAZ()

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

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

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

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

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

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

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

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

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

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

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

◆ homflyLM()

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

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

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

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

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

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

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

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

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

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

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

◆ hopf()

static Link* regina::ExampleLink::hopf ( )
static

Returns a two-crossing diagram of the Hopf link.

This is the variant in which both crossings are positive.

Returns
a newly constructed link, which must be destroyed by the caller of this routine.

◆ id()

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

An integer that uniquely identifies this strand within the link.

This integer will be 2c+s, where c is the index of the crossing, and s is 0 or 1 for the lower or upper strand respectively.

If this is a null reference, then id() will return -1.

A strand can be restored from its ID by calling Link::strand().

Returns
the unique ID of this strand within the link.

◆ index() [1/2]

int regina::Crossing::index ( ) const
inline

Returns the index of this crossing within the overall link.

If the link contains n crossings, then the index will be a number between 0 and n-1 inclusive.

Warning
The index of this crossing might change if other crossings are added or removed.
Returns
the index of this crossing.

◆ index() [2/2]

int regina::ModelLinkGraphNode::index ( ) const
inline

Returns the index of this node within the overall graph.

If the graph contains n nodes, then the index will be a number between 0 and n-1 inclusive.

Warning
The index of this node might change if other nodes are added or removed.
Returns
the index of this node.

◆ initialChars() [1/3]

virtual void regina::XMLLinkConnectionsReader::initialChars ( const std::string &  chars)
virtual

Signifies that the initial text belonging to this XML element has been read.

The initial text is everything between the opening tag and the first subelement or closing tag.

The default implementation does nothing.

Parameters
charsthe initial text for this element.

Reimplemented from regina::XMLElementReader.

◆ initialChars() [2/3]

virtual void regina::XMLLinkComponentsReader::initialChars ( const std::string &  chars)
virtual

Signifies that the initial text belonging to this XML element has been read.

The initial text is everything between the opening tag and the first subelement or closing tag.

The default implementation does nothing.

Parameters
charsthe initial text for this element.

Reimplemented from regina::XMLElementReader.

◆ initialChars() [3/3]

virtual void regina::XMLLinkCrossingsReader::initialChars ( const std::string &  chars)
overridevirtual

Signifies that the initial text belonging to this XML element has been read.

The initial text is everything between the opening tag and the first subelement or closing tag.

The default implementation does nothing.

Parameters
charsthe initial text for this element.

Reimplemented from regina::XMLElementReader.

◆ insertTorusLink()

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

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

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

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

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

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

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

◆ intelligentSimplify()

bool regina::Link::intelligentSimplify ( )

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

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

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

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

This routine will never reflect or reverse the link.

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

◆ internalClonePacket()

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

Makes a newly allocated copy of this packet.

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

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

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

Implements regina::Packet.

◆ isAlternating()

bool regina::Link::isAlternating ( ) const

Returns whether this knot diagram is alternating.

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

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

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

◆ isEmpty()

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

Determines whether this link is empty.

An empty link is one with no components at all.

Returns
true if and only if this link is empty.

◆ isValid()

bool regina::ModelLinkGraphCells::isValid ( ) const
inline

Determines whether the underlying graph is non-empty with a planar embedding, assuming that it is already known to be connected.

As described in the class notes, this class can only work with non-empty connected graphs where the corresponding ModelLinkGraph object also describes a planar embedding.

The constructor for this class requires you to pass a graph that is already known to be connected. However, assuming the graph is connected, the constructor then tests for the remaining conditions. This routine returns the results of these tests: if the underlying graph is empty or does not describe a planar embedding, then this routine will return false.

This routine is constant time, since the necessary work will have already been completed by the class constructor.

Warning
Most of the routines in this class require isValid() to return true. Essentially, if isValid() returns false, you should not attempt to query the details of the cell decomposition. See the preconditions on individual routines for further details.
Returns
true if and only if the underlying ModelLinkGraph describes a planar embedding of a non-empty graph.

◆ jenkins() [1/2]

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

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

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

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

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

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

◆ jenkins() [2/2]

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

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

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

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

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

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

◆ jones()

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

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

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

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

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

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

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

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

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

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

◆ jump()

void regina::StrandRef::jump ( )
inline

Jumps to the other strand at the same crossing.

This reference will be changed directly. The crossing will remain the same, but the strand will switch from lower to upper or vice versa.

◆ kinoshitaTerasaka()

static Link* regina::ExampleLink::kinoshitaTerasaka ( )
static

Returns the 11-crossing Kinoshita-Terasaka knot.

This is the reflection of K11n42 in the Knot Atlas, and is a mutant of the Conway knot. It has trivial Alexander polynomial.

Returns
a newly constructed link, which must be destroyed by the caller of this routine.

◆ knotSig()

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

Constructs the signature for this knot diagram.

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

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

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

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

This routine runs in quadratic time.

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

◆ knowsBracket()

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

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

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

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

◆ knowsHomfly()

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

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

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

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

◆ knowsJones()

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

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

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

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

◆ Link() [1/5]

regina::Link::Link ( )
inline

Constructs an empty link.

This will have zero components.

◆ Link() [2/5]

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

Constructs a new copy of the given link.

The packet tree structure and packet label are not copied.

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

Parameters
copythe link to copy.

◆ Link() [3/5]

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

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

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

◆ Link() [4/5]

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

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

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

This list may grow in future versions of Regina.

Regina will also set the packet label accordingly.

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

Parameters
descriptiona string that describes a knot or link.

◆ Link() [5/5]

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

Constructs the unlink with the given number of components.

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

◆ linking()

long regina::Link::linking ( ) const

Returns the linking number of this link.

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

The algorithm to compute linking number is linear time.

Returns
the linking number.

◆ lower()

StrandRef regina::Crossing::lower ( )
inline

Returns a reference to the strand running under this crossing.

This is equivalent to directly constructing StrandRef(this, 0).

Note that lower() and under() are synonyms.

Returns
a reference to the lower strand for this crossing.

◆ ModelLinkGraph() [1/2]

regina::ModelLinkGraph::ModelLinkGraph ( )
inline

Constructs an empty graph.

◆ ModelLinkGraph() [2/2]

regina::ModelLinkGraph::ModelLinkGraph ( const ModelLinkGraph copy)

Constructs a new copy of the given graph.

Parameters
copythe graph to copy.

◆ ModelLinkGraphArc() [1/3]

regina::ModelLinkGraphArc::ModelLinkGraphArc ( )
inline

Initialises this to a null arc.

The pointer returned by node() will be null, and the integer returned by arc() will be 0.

◆ ModelLinkGraphArc() [2/3]

regina::ModelLinkGraphArc::ModelLinkGraphArc ( const ModelLinkGraphArc )
default

Default copy constructor.

◆ ModelLinkGraphArc() [3/3]

regina::ModelLinkGraphArc::ModelLinkGraphArc ( ModelLinkGraphNode node,
int  arc 
)
inline

Initialises this to the given arc exiting the given node of a model graph.

Recall that the four arcs exiting a node are numbered 0,1,2,3 in a clockwise order around the node.

The given node may be null, in which case this will become a null arc. If you are creating a null arc, then it is highly recommended that you pass arc as 0 also, so that comparison tests treat this null reference as equal to a null reference created by the zero-argument constructor.

Parameters
nodethe node of the model graph that this arc exits.
arcan integer in the range 0 to 3 inclusive, indicating which of the four arcs exiting node this represents.

◆ monster()

static Link* regina::ExampleLink::monster ( )
static

Returns the monster unknot, a 10-crossing diagram of the unknot that is difficult to untangle.

Returns
a newly constructed link, which must be destroyed by the caller of this routine.

◆ negate()

void regina::Tangle::negate ( )

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

In Conway's notation, this negates the tangle.

◆ next() [1/3]

StrandRef regina::StrandRef::next ( ) const
inline

Returns the crossing reference that comes immediately after this when walking forward along the direction of the link.

Equivalently, this routine returns the reference that would be obtained by calling the increment (++) operator (but, unlike the increment operator, this routine does not actually change the current reference).

Precondition
This is not a null reference, i.e., crossing() does not return null.
Returns
the crossing reference that follows this.

◆ next() [2/3]

ModelLinkGraphArc regina::ModelLinkGraphArc::next ( ) const
inline

Returns the next arc after this when walking through the graph as though it were a link, in a direction away from the current node.

This routine will move to the other endpoint of the graph edge described by this arc, and will then return the opposite arc at the resulting node (i.e., not just pointing backwards along the same edge).

For any arc a, calling a.next() is equivalent to calling a.traverse().opposite().

Precondition
This is not a null arc, i.e., node() does not return null.
Returns
the next arc after this when walking through the graph as though it were a link.

◆ next() [3/3]

StrandRef regina::Crossing::next ( int  strand) const
inline

Returns the crossing reference that immediately follows this when walking forward in the direction of the link along one of the two strands that pass at this crossing.

Which strand we follow is indicated by the argument strand.

Note that for a crossing c, calling c.next(s) is equivalent to calling c.strand(s).next().

Parameters
strandeither 1 to walk forward along the upper strand, or 0 to walk forward along the lower strand.
Returns
a reference to the next crossing after this along the given strand.

◆ niceTreeDecomposition()

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

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

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

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

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

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

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

Returns
a nice tree decomposition of this link diagram.

◆ node() [1/2]

ModelLinkGraphNode * regina::ModelLinkGraphArc::node ( ) const
inline

The node of the model graph from which this arc exits.

Returns
the corresponding node, or null if this is a null arc.

◆ node() [2/2]

ModelLinkGraphNode * regina::ModelLinkGraph::node ( size_t  index) const
inline

Returns the node at the given index within this graph.

For a graph with n nodes, the nodes are numbered from 0 to n-1 inclusive.

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

◆ numClosure()

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

Forms the numerator closure of this tangle.

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

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

◆ operator bool() [1/2]

regina::StrandRef::operator bool ( ) const
inline

Tests whether this is a non-null reference.

Python
This is not available to python users. Instead you can simply test whether crossing() == None.
Returns
true if this is not a null reference (i.e., crossing() does not return a null pointer), or false if this is a null reference.

◆ operator bool() [2/2]

regina::ModelLinkGraphArc::operator bool ( ) const
inline

Tests whether this is a non-null arc.

Python
This is not available to python users. Instead you can simply test whether node() == None.
Returns
true if this is not a null arc (i.e., node() does not return a null pointer), or false if this is a null arc.

◆ operator!=() [1/4]

bool regina::ArcIterator::operator!= ( const ArcIterator rhs) const
inline

Tests whether this and the given iterator are different.

Note
This routine only compares the indices of the crossings and the upper/lower strand markings. It does not examine whether this and the given iterator refer to the same underlying link.
Parameters
rhsthe iterator to compare with this.
Returns
true if and only if the two iterators are different.

◆ operator!=() [2/4]

bool regina::CrossingIterator::operator!= ( const CrossingIterator rhs) const
inline

Tests whether this and the given iterator are different.

Note
This routine only compares the indices of the crossings. It does not examine whether this and the given iterator refer to the same underlying link.
Parameters
rhsthe iterator to compare with this.
Returns
true if and only if the two iterators are different.

◆ operator!=() [3/4]

bool regina::ModelLinkGraphArc::operator!= ( const ModelLinkGraphArc rhs) const
inline

Tests whether this and the given arc reference are not identical.

Two references are identical if and only if they return the same values for both node() and arc().

Warning
If you create a null arc by calling ModelLinkGraphArc(null, i) for some non-zero i, then this will not be considered equal to the null arc created by calling ModelLinkGraphArc(), since the latter is equivalent to calling ModelLinkGraphArc(null, 0).

true if and only if this and rhs are not identical.

◆ operator!=() [4/4]

bool regina::StrandRef::operator!= ( const StrandRef rhs) const
inline

Tests whether this and the given reference are not identical.

Two references are identical if and only if they return the same values for both crossing() and strand().

Warning
If you create a null reference by calling StrandRef(null, 1) then this will not be considered equal to the null reference created by calling StrandRef(), since the latter is equivalent to calling StrandRef(null, 0).

true if and only if this and rhs are not identical.

◆ operator*() [1/2]

Crossing * regina::CrossingIterator::operator* ( ) const
inline

Returns the crossing to which this iterator points.

Precondition
This iterator is not past-the-end.
Returns
the crossing to which this iterator points.

◆ operator*() [2/2]

StrandRef regina::ArcIterator::operator* ( ) const
inline

Returns the directed arc to which this iterator points.

See the StrandRef documentation for details on how a StrandRef object is used to identify a directed arc.

Precondition
This iterator is not past-the-end.
Returns
the directed arc to which this iterator points.

◆ operator++() [1/8]

StrandRef & regina::StrandRef::operator++ ( )
inline

Moves this reference forward along the direction of the link until it reaches the next crossing.

(Of course, if the link contains a trivial twist then this may in fact return to the same crossing but the other strand).

This is a preincrement operator: the object will be changed, and then a reference to it will be returned.

Precondition
This is not a null reference, i.e., crossing() does not return null.
Python
This routine is not available; however, the postincrement operator is available under the name inc().
Returns
a reference to this object.

◆ operator++() [2/8]

CrossingIterator & regina::CrossingIterator::operator++ ( )
inline

Preincrement operator.

Returns
a reference to this iterator.

◆ operator++() [3/8]

ArcIterator & regina::ArcIterator::operator++ ( )
inline

Preincrement operator.

Returns
a reference to this iterator.

◆ operator++() [4/8]

ModelLinkGraphArc & regina::ModelLinkGraphArc::operator++ ( )
inline

Changes to the next outgoing link arc from the same node.

This effectively rotates the arc in a clockwise direction around the node. In particular, it increments the value returned by arc(), modulo 4.

This is a preincrement operator: the object will be changed, and then a reference to it will be returned.

Precondition
This is not a null arc, i.e., node() does not return null.
Python
This routine is not available; however, the postincrement operator is available under the name inc().
Returns
a reference to this object.

◆ operator++() [5/8]

StrandRef regina::StrandRef::operator++ ( int  )
inline

Moves this reference forward along the direction of the link until it reaches the next crossing.

(Of course, if the link contains a trivial twist then this may in fact return to the same crossing but the other strand).

This is a postincrement operator: the object will be changed, but a copy of the original reference will be returned.

Precondition
This is not a null reference, i.e., crossing() does not return null.
Python
This routine is available under the name inc().
Returns
a copy of this object before the change took place.

◆ operator++() [6/8]

CrossingIterator regina::CrossingIterator::operator++ ( int  )
inline

Postincrement operator.

Returns
a copy of this iterator before it was incremented.

◆ operator++() [7/8]

ArcIterator regina::ArcIterator::operator++ ( int  )
inline

Postincrement operator.

Returns
a copy of this iterator before it was incremented.

◆ operator++() [8/8]

ModelLinkGraphArc regina::ModelLinkGraphArc::operator++ ( int  )
inline

Changes to the next outgoing link arc from the same node.

This effectively rotates the arc in a clockwise direction around the node. In particular, it increments the value returned by arc(), modulo 4.

This is a postincrement operator: the object will be changed, but a copy of the original arc will be returned.

Precondition
This is not a null arc, i.e., node() does not return null.
Python
This routine is available under the name inc().
Returns
a copy of this object before the change took place.

◆ operator--() [1/4]

StrandRef & regina::StrandRef::operator-- ( )
inline

Moves this reference backward against the direction of the link until it reaches the previous crossing.

(Of course, if the link contains a trivial twist then this may in fact return to the same crossing but the other strand).

This is a preincrement operator: the object will be changed, and then a reference to it will be returned.

Precondition
This is not a null reference, i.e., crossing() does not return null.
Python
This routine is not available; however, the postincrement operator is available under the name dec().
Returns
a reference to this object.

◆ operator--() [2/4]

ModelLinkGraphArc & regina::ModelLinkGraphArc::operator-- ( )
inline

Changes to the previous outgoing link arc from the same node.

This effectively rotates the arc in an anticlockwise direction around the node. In particular, it decrements the value returned by arc(), modulo 4.

This is a predecrement operator: the object will be changed, and then a reference to it will be returned.

Precondition
This is not a null arc, i.e., node() does not return null.
Python
This routine is not available; however, the postdecrement operator is available under the name dec().
Returns
a reference to this object.

◆ operator--() [3/4]

StrandRef regina::StrandRef::operator-- ( int  )
inline

Moves this reference backward against the direction of the link until it reaches the previous crossing.

(Of course, if the link contains a trivial twist then this may in fact return to the same crossing but the other strand).

This is a postincrement operator: the object will be changed, but a copy of the original reference will be returned.

Precondition
This is not a null reference, i.e., crossing() does not return null.
Python
This routine is available under the name dec().
Returns
a copy of this object before the change took place.

◆ operator--() [4/4]

ModelLinkGraphArc regina::ModelLinkGraphArc::operator-- ( int  )
inline

Changes to the previous outgoing link arc from the same node.

This effectively rotates the arc in an anticlockwise direction around the node. In particular, it decrements the value returned by arc(), modulo 4.

This is a postdecrement operator: the object will be changed, but a copy of the original arc will be returned.

Precondition
This is not a null arc, i.e., node() does not return null.
Python
This routine is available under the name dec().
Returns
a copy of this object before the change took place.

◆ operator<<() [1/2]

std::ostream & regina::operator<< ( std::ostream &  out,
const ModelLinkGraphArc a 
)
inline

Writes a depiction of the given arc reference to the given output stream.

Parameters
outthe output stream to which to write.
athe arc reference to write.
Returns
a reference to the given output stream.

◆ operator<<() [2/2]

std::ostream & regina::operator<< ( std::ostream &  out,
const StrandRef s 
)
inline

Writes a depiction of the given strand reference to the given output stream.

The reference will be written in the form ^n or _n, denoting the upper or lower strand at crossing n respectively. For example, the upper strand of crossing 7 will be written as ^7.

Parameters
outthe output stream to which to write.
sthe reference to write.
Returns
a reference to the given output stream.

◆ operator=() [1/4]

ArcIterator& regina::ArcIterator::operator= ( const ArcIterator )
default

Default assignment operator.

Returns
a reference to this iterator.

◆ operator=() [2/4]

CrossingIterator& regina::CrossingIterator::operator= ( const CrossingIterator )
default

Default assignment operator.

Returns
a reference to this iterator.

◆ operator=() [3/4]

ModelLinkGraphArc& regina::ModelLinkGraphArc::operator= ( const ModelLinkGraphArc )
default

Default assignment operator.

Returns
a reference to this object.

◆ operator=() [4/4]

StrandRef& regina::StrandRef::operator= ( const StrandRef )
default

Default assignment operator.

Returns
a reference to this object.

◆ operator==() [1/4]

bool regina::ArcIterator::operator== ( const ArcIterator rhs) const
inline

Tests whether this and the given iterator are equal.

Note
This routine only compares the indices of the crossings and the upper/lower strand markings. It does not examine whether this and the given iterator refer to the same underlying link.
Parameters
rhsthe iterator to compare with this.
Returns
true if and only if the two iterators are equal.

◆ operator==() [2/4]

bool regina::CrossingIterator::operator== ( const CrossingIterator rhs) const
inline

Tests whether this and the given iterator are equal.

Note
This routine only compares the indices of the crossings. It does not examine whether this and the given iterator refer to the same underlying link.
Parameters
rhsthe iterator to compare with this.
Returns
true if and only if the two iterators are equal.

◆ operator==() [3/4]

bool regina::ModelLinkGraphArc::operator== ( const ModelLinkGraphArc rhs) const
inline

Tests whether this and the given arc reference are identical.

Two references are identical if and only if they return the same values for both node() and arc().

Warning
If you create a null arc by calling ModelLinkGraphArc(null, i) for some non-zero i, then this will not be considered equal to the null arc created by calling ModelLinkGraphArc(), since the latter is equivalent to calling ModelLinkGraphArc(null, 0).

true if and only if this and rhs are identical.

◆ operator==() [4/4]

bool regina::StrandRef::operator== ( const StrandRef rhs) const
inline

Tests whether this and the given reference are identical.

Two references are identical if and only if they return the same values for both crossing() and strand().

Warning
If you create a null reference by calling StrandRef(null, 1) then this will not be considered equal to the null reference created by calling StrandRef(), since the latter is equivalent to calling StrandRef(null, 0).

true if and only if this and rhs are identical.

◆ opposite()

ModelLinkGraphArc regina::ModelLinkGraphArc::opposite ( ) const
inline

Returns the arc that exits the same node as this, but from the opposite side.

Recall that the four arcs exiting each node are numbered in clockwise order. The return value will therefore have the same node() as this, but its arc() value will be two more than this (modulo 4).

Note that, for any arc a, a.opposite().opposite() is identical to a.

Precondition
This is not a null arc, i.e., node() does not return null.
Returns
the opposite arc exiting the same node.

◆ orientedGauss() [1/4]

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

Outputs an oriented Gauss code for this knot.

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

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

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

The string will not contain any newlines.

Note
There is another variant of this routine that, instead of returning a string, writes directly to an output stream.
Returns
an oriented Gauss code for this knot, or the empty string if this is a link with zero or multiple components.

◆ orientedGauss() [2/4]

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

Outputs an oriented Gauss code for this tangle.

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

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

The string that is returned will not contain any newlines.

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

◆ orientedGauss() [3/4]

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

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

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

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

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

The output will not contain any newlines.

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

◆ orientedGauss() [4/4]

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

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

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

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

The output will not contain any newlines.

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

◆ over()

StrandRef regina::Crossing::over ( )
inline

Returns a reference to the strand running over this crossing.

This is equivalent to directly constructing StrandRef(this, 1).

Note that upper() and over() are synonyms.

Returns
a reference to the upper strand for this crossing.

◆ pace()

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

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

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

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

See the writePACE() notes for further details.

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

◆ packet()

Packet * regina::XMLLinkReader::packet ( )
inlineoverridevirtual

Returns the newly allocated packet that has been read by this element reader.

Deallocation of this new packet is not the responsibility of this class. Once this routine gives a non-zero return value, it should continue to give the same non-zero return value from this point onwards.

If this routine is ever to give a non-zero return value, it must be giving that non-zero return value by the time the first child packet or packet tag is encountered; otherwise child packets will not be inserted into the packet tree and/or packet tags will not be added.

The newly allocated packet should not be given a packet label. This will be done by XMLPacketReader::endSubElement().

The newly allocated packet may or may not be inserted in the packet tree structure; this does not matter (although if it is inserted it must be inserted in the correct place).

The newly allocated packet should not be given any associated packet tags. This will be done by XMLPacketReader::startSubElement().

The default implementation returns 0.

Returns
the packet that has been read, or 0 if packet reading is incomplete, the packet should be ignored or an error occurred.

Reimplemented from regina::XMLPacketReader.

◆ parallel()

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

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

This routine creates a new link by:

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

This link will not be modified.

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

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

◆ plantri()

std::string regina::ModelLinkGraph::plantri ( ) const

Outputs this graph in the ASCII text format used by plantri.

The software plantri, by Gunnar Brinkmann and Brendan McKay, can be used to enumerate 4-valent planar graphs (amongst many other things). This routine outputs this graph in a format that mimics plantri's own dual ASCII format (i.e., the format that plantri outputs when run with the flags -adq).

Specifically, the output will be a comma-separated sequence of alphabetical strings. The ith such string will consist of four lower-case letters, encoding the endpoints of the four edges in clockwise order that leave node i. The letters a,b,c,... represent nodes 0,1,2,... respectively. An example of such a string is:

bcdd,aeec,abfd,acfa,bffb,ceed

This routine is an inverse to fromPlantri(): for any graph g that satisfies the preconditions below, fromPlantri(g.plantri()) is identical to g. Likewise, for any string s that satisfies the preconditions for fromPlantri(), calling fromPlantri(s).plantri() will recover the original string s.

It is important to note the preconditions below: in particular, that this graph must be dual to a simple quadrangulation of the sphere. This is because the planar embeddings for more general graphs (i.e., the duals of non-simple quadrangulations) cannot always be uniquely reconstructed from their plantri output.

Note
The output of this function might not correspond to any possible output from the program plantri itself. This is because plantri only outputs graphs with a certain canonical labelling. In contrast, plantri() can be called on any graph that satisfies the preconditions below, and it will preserve the labels of the nodes and the order of the arcs around each node.
Precondition
This graph is connected.
This graph has between 1 and 26 nodes inclusive.
The dual to this graph is a simple quadrangulation of the sphere. In particular, the dual must not have any parallel edges. Note that any graph that fails this condition will the model graph for a link diagram that is an "obvious" connected sum.
Returns
a plantri format ASCII representation of this graph.

◆ prev() [1/3]

StrandRef regina::StrandRef::prev ( ) const
inline

Returns the crossing reference that comes immediately before this when walking backward against the direction of the link.

Equivalently, this routine returns the reference that would be obtained by calling the decrement (–) operator (but, unlike the decrement operator, this routine does not actually change the current reference).

Precondition
This is not a null reference, i.e., crossing() does not return null.
Returns
the crossing reference that precedes this.

◆ prev() [2/3]

ModelLinkGraphArc regina::ModelLinkGraphArc::prev ( ) const
inline

Returns the previous arc before this when walking through the graph as though it were a link, in a direction away from the* current node.

This routine will jump to the opposite arc at the current node, and then move to the other endpoint of the graph edge described by that opposite arc.

For any arc a, calling a.prev() is equivalent to calling a.opposite().traverse().

Precondition
This is not a null arc, i.e., node() does not return null.
Returns
the previous arc before this when walking through the graph as though it were a link.

◆ prev() [3/3]

StrandRef regina::Crossing::prev ( int  strand) const
inline

Returns the crossing reference that immediately precedes this when walking backward against the direction of the link along one of the two strands that pass at this crossing.

Which strand we follow is indicated by the argument strand.

Note that for a crossing c, calling c.prev(s) is equivalent to calling c.strand(s).prev().

Parameters
strandeither 1 to walk backward along the upper strand, or 0 to walk backward along the lower strand.
Returns
a reference to the previous crossing before this along the given strand.

◆ r1() [1/3]

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

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

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

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

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

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

Warning
A side-effect of this move is that, because one crossing is being removed, the other crossings in the link may be reindexed. However, no crossings other than the one involved in this move will be destroyed.
Precondition
If perform is true but check is false, then it must be known in advance that this move can be performed at the given location.
The given crossing is either a null pointer, or else some crossing in this link.
Parameters
crossingidentifies the crossing to be removed.
checktrue if we are to check whether the move can be performed at the given location.
performtrue if we should actually perform the move.
Returns
If check is true, this function returns true if and only if the move can be performed. If check is false, this function always returns true.

◆ r1() [2/3]

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

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

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

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

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

◆ r1() [3/3]

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

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

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

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

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

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

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

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

Precondition
If perform is true but check is false, then it must be known in advance that this move can be performed at the given location.
The given strand reference is either a null reference, or else refers to some strand of some crossing in this link.
Parameters
arcidentifies the arc of the link in which the new twist will be introduced, as described above.
side0 if the twist should be introduced on the left of the arc (when walking along the arc in the forward direction), or 1 if the twist should be introduced on the right of the arc.
signthe sign of the new crossing that will be introduced as part of the twist; this must be +1 or -1.
checktrue if we are to check whether the move can be performed at the given location.
performtrue if we should actually perform the move.
Returns
If check is true, this function returns true if and only if the move can be performed. If check is false, this function always returns true.

◆ r2() [1/5]

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

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

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

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

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

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

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

Warning
A side-effect of this move is that, because two crossings are being removed, the other crossings in the link may be reindexed. However, no crossings other than the two involved in this move will be destroyed.
Precondition
If perform is true but check is false, then it must be known in advance that this move can be performed at the given location.
The given crossing is either a null pointer, or else some crossing in this link.
Parameters
crossingidentifies the crossing at the beginning of the "upper" arc that features in this move, as described above.
checktrue if we are to check whether the move is legal.
performtrue if we should actually perform the move.
Returns
If check is true, this function returns true if and only if the requested move is legal. If check is false, this function always returns true.

◆ r2() [2/5]

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

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

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

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

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

◆ r2() [3/5]

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

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

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

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

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

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

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

Warning
A side-effect of this move is that, because two crossings are being removed, the other crossings in the link may be reindexed. However, no crossings other than the two involved in this move will be destroyed.
Precondition
If perform is true but check is false, then it must be known in advance that this move can be performed at the given location.
The given strand reference is either a null reference, or else refers to some strand of some crossing in this link.
Parameters
arcidentifies one of the arcs of the bigon about which the move will be performed, as described above.
checktrue if we are to check whether the move is legal.
performtrue if we should actually perform the move.
Returns
If check is true, this function returns true if and only if the requested move is legal. If check is false, this function always returns true.

◆ r2() [4/5]

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

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

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

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

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

◆ r2() [5/5]

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

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

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

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

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

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

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

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

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

Precondition
If perform is true but check is false, then it must be known in advance that this move can be performed at the given location.
Each of the given strand references is either a null reference, or else refers to some strand of some crossing in this link.
Warning
The check for this move is expensive (linear time), since it includes testing whether both sides-of-arcs belong to the same 2-cell of the knot diagram.
Parameters
upperArcidentifies the arc of the link which will be passed over the other, as described above.
upperSide0 if the new overlap should take place on the left of upperArc (when walking along upperArc in the forward direction), or 1 if the new overlap should take place on the right of upperArc.
lowerArcidentifies the arc of the link which will be passed beneath the other, as described above.
lowerSide0 if the new overlap should take place on the left of lowerArc (when walking along lowerArc in the forward direction), or 1 if the new overlap should take place on the right of lowerArc.
checktrue if we are to check whether the move can be performed at the given location.
performtrue if we should actually perform the move.
Returns
If check is true, this function returns true if and only if the move can be performed. If check is false, this function always returns true.

◆ r3() [1/2]

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

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

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

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

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

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

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

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

Precondition
If perform is true but check is false, then it must be known in advance that this move can be performed at the given location.
The given crossing is either a null pointer, or else some crossing in this link.
Parameters
crossingidentifies the crossing at the beginning of the "uppermost" arc that features in this move, as described above.
side0 if the third crossing of the triangle is located to the left of the uppermost arc (when walking along the arc in the forward direction), or 1 if the third crossing is located on the right of the uppermost arc.
checktrue if we are to check whether the move can be performed at the given location.
performtrue if we should actually perform the move.
Returns
If check is true, this function returns true if and only if the move can be performed. If check is false, this function always returns true.

◆ r3() [2/2]

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

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

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

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

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

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

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

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

Precondition
If perform is true but check is false, then it must be known in advance that this move can be performed at the given location.
The given strand reference is either a null reference, or else refers to some strand of some crossing in this link.
Parameters
arcidentifies one of the arcs of the triangle about which the move will be performed, as described above.
side0 if the third crossing of the triangle is located to the left of the arc (when walking along the arc in the forward direction), or 1 if the third crossing is located on the right of the arc.
checktrue if we are to check whether the move can be performed at the given location.
performtrue if we should actually perform the move.
Returns
If check is true, this function returns true if and only if the move can be performed. If check is false, this function always returns true.

◆ reflect() [1/2]

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.

◆ reflect() [2/2]

void regina::ModelLinkGraph::reflect ( )

Converts this graph into its reflection.

This routine simply reverses (and also cycles) the order of outgoing arcs around every node.

◆ resolve()

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

Resolves the given crossing.

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

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

◆ reverse()

void regina::Link::reverse ( )

Reverses the orientation of every component of this link.

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

◆ rewrite()

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

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

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

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

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

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

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

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

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

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

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

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

◆ rotate()

void regina::Link::rotate ( )

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

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

◆ sign()

int regina::Crossing::sign ( ) const
inline

Returns the sign of this crossing.

This will be +1 for a positive crossing, or -1 for a negative crossing.

See the Crossing class notes for diagrams of positive and negative crossings

Returns
the sign of this crossing.

◆ simplifyExhaustive()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

◆ simplifyToLocalMinimum() [1/2]

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

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

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

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

This routine will never reflect or reverse the link.

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

◆ simplifyToLocalMinimum() [2/2]

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

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

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

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

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

◆ size() [1/4]

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

Returns the number of crossings in this link.

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

Returns
the number of crossings.

◆ size() [2/4]

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

Returns the number of nodes in this graph.

Returns
the number of nodes.

◆ size() [3/4]

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

Returns the number of crossings in this tangle.

Returns
the number of crossings.

◆ size() [4/4]

size_t regina::ModelLinkGraphCells::size ( size_t  cell) const
inline

Returns the number of arcs aloung the boundary of the given 2-cell.

If the given cell is a k-gon, then this routine returns the integer k.

Precondition
The underlying ModelLinkGraph is non-empty, connected, and describes a planar graph embedding. Note that connectivity is already required by the class constructor, and you can test the remaining conditions by calling isValid().
Parameters
cellindicates which cell to query; this must be between 0 and countCells()-1 inclusive.
Returns
the size of the correpsonding 2-cell.

◆ startContentSubElement()

XMLElementReader * regina::XMLLinkReader::startContentSubElement ( const std::string &  subTagName,
const regina::xml::XMLPropertyDict subTagProps 
)
inlineoverridevirtual

Used instead of startSubElement() for XML subelements that are not child packets or packet tags.

The default implementation returns a new XMLElementReader which can be used to ignore the subelement completely.

Parameters
subTagNamethe name of the subelement opening tag.
subTagPropsthe properties associated with the subelement opening tag.
Returns
a newly created element reader that will be used to parse the subelement. This class should not take care of the new reader's destruction; that will be done by the parser.

Reimplemented from regina::XMLPacketReader.

◆ startElement() [1/2]

void regina::XMLLinkComponentsReader::startElement ( const std::string &  tagName,
const regina::xml::XMLPropertyDict tagProps,
XMLElementReader parentReader 
)
virtual

Signifies that parsing of this XML element is beginning.

The default implementation does nothing.

Parameters
tagNamethe name of the opening tag for this element.
tagPropsthe properties associated with the opening tag.
parentReaderthe reader currently parsing the parent XML element, or 0 if this is the top-level element. If this paraneter is non-zero, it is guaranteed that startSubElement() has already been called upon the parent reader.

Reimplemented from regina::XMLElementReader.

◆ startElement() [2/2]

void regina::XMLLinkCrossingsReader::startElement ( const std::string &  tagName,
const regina::xml::XMLPropertyDict tagProps,
XMLElementReader parentReader 
)
overridevirtual

Signifies that parsing of this XML element is beginning.

The default implementation does nothing.

Parameters
tagNamethe name of the opening tag for this element.
tagPropsthe properties associated with the opening tag.
parentReaderthe reader currently parsing the parent XML element, or 0 if this is the top-level element. If this paraneter is non-zero, it is guaranteed that startSubElement() has already been called upon the parent reader.

Reimplemented from regina::XMLElementReader.

◆ strand() [1/3]

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

Indicates whether this reference points to the upper or lower strand of the relevant crossing.

A value of 1 denotes the upper strand (which passes over the crossing), and a value of 0 denotes the lower strand (which passes under the crossing).

The information returned by crossing() and strand() together pinpoint exactly which strand of the link this reference points to.

Returns
either 0 or 1 to indicate the strand.

◆ strand() [2/3]

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

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

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

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

◆ strand() [3/3]

StrandRef regina::Crossing::strand ( int  which)
inline

Returns a reference to one of the two strands of the link that pass each other at this crossing.

This is equivalent to directly constructing StrandRef(this, which).

Note that upper() and over() are synonyms for strand(1), and lower() and under() are synonyms for strand(0).

Parameters
whicheither 1 to indicate the upper strand, or 0 to indicate the lower strand.
Returns
a reference to the given strand at this crossing.

◆ StrandRef() [1/3]

regina::StrandRef::StrandRef ( )
inline

Initialises this to a null reference.

The pointer returned by crossing() will be null, and the integer returned by strand() will be 0.

◆ StrandRef() [2/3]

regina::StrandRef::StrandRef ( const StrandRef )
default

Default copy constructor.

◆ StrandRef() [3/3]

regina::StrandRef::StrandRef ( Crossing crossing,
int  strand 
)
inline

Initialises this to the given strand of the given crossing.

The given crossing may be null, in which case this will become a null reference. If you are creating a null reference, then it is highly recommended that you pass strand as 0, so that comparison tests treat this null reference as equal to a null reference created by the zero-argument constructor.

Parameters
crossingthe crossing being identified.
strand0 to denote the strand running under the crossing, or 1 to denote the strand running over the crossing.

◆ swapContents() [1/3]

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

Swaps the contents of this and the given link.

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

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

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

Parameters
otherthe link whose contents should be swapped with this.

◆ swapContents() [2/3]

void regina::ModelLinkGraph::swapContents ( ModelLinkGraph other)
inline

Swaps the contents of this and the given graph.

All nodes that belong to this graph will be moved to other, and all nodes that belong to other will be moved to this graph.

In particular, any ModelLinkGraphNode pointers or references and any ModelLinkGraphArc objects will remain valid.

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

Parameters
otherthe graph whose contents should be swapped with this.

◆ swapContents() [3/3]

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

Swaps the contents of this and the given tangle.

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

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

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

Parameters
otherthe link whose contents should be swapped with this.

◆ Tangle() [1/5]

regina::Tangle::Tangle ( )
inline

Constructs the zero tangle.

This is the horizontal tangle with no crossings.

◆ Tangle() [2/5]

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

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

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

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

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

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

◆ Tangle() [3/5]

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

Constructs a new copy of the given tangle.

Parameters
copythe tangle to copy.

◆ Tangle() [4/5]

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

Constructs a rational tangle with the given parameters.

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

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

◆ Tangle() [5/5]

regina::Tangle::Tangle ( int  twists)

Constructs a tangle from the given number of twists.

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

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

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

◆ torus()

static Link* regina::ExampleLink::torus ( int  p,
int  q 
)
static

Returns the (p,q) torus link.

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

All of the crossings in the resulting link will be positive.

Parameters
pthe first parameter of the torus link; this must be strictly non-negative.
qthe second parameter of the torus link; this must also be strictly non-negative.
Returns
the (p, q) torus link.

◆ translate() [1/2]

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

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

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

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

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

◆ translate() [2/2]

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

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

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

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

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

◆ traverse()

ModelLinkGraphArc regina::ModelLinkGraphArc::traverse ( ) const
inline

Returns the same edge of the model graph, but seen from the other endpoint.

Recall that each undirected edge of a model graph has two corresponding ModelLinkGraphArc objects, one for each of its endpoints. If this object represents one of these arcs for some underlying edge of the graph, then then return value represents the other.

Note that, for any arc a, a.traverse().traverse() is identical to a.

Precondition
This is not a null arc, i.e., node() does not return null.
Returns
the arc at the other end of the underlying edge of the model graph.

◆ trefoil()

static Link* regina::ExampleLink::trefoil ( )
static

Returns a three-crossing diagram of the right-hand trefoil.

This returns the same knot as trefoilRight().

Returns
a newly constructed link, which must be destroyed by the caller of this routine.

◆ trefoilLeft()

static Link* regina::ExampleLink::trefoilLeft ( )
static

Returns a three-crossing diagram of the left-hand trefoil.

Returns
a newly constructed link, which must be destroyed by the caller of this routine.

◆ trefoilRight()

static Link* regina::ExampleLink::trefoilRight ( )
static

Returns a three-crossing diagram of the right-hand trefoil.

This returns the same knot as trefoil().

Returns
a newly constructed link, which must be destroyed by the caller of this routine.

◆ turn()

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

Rotates this tangle by 90 degrees.

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

◆ twist()

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

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

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

◆ type()

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

Returns the type of this tangle.

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

Returns
the type of this crossing.

◆ under()

StrandRef regina::Crossing::under ( )
inline

Returns a reference to the strand running under this crossing.

This is equivalent to directly constructing StrandRef(this, 0).

Note that lower() and under() are synonyms.

Returns
a reference to the lower strand for this crossing.

◆ unknot()

static Link* regina::ExampleLink::unknot ( )
static

Returns a zero-crossing diagram of the unknot.

Returns
a newly constructed link, which must be destroyed by the caller of this routine.

◆ upper()

StrandRef regina::Crossing::upper ( )
inline

Returns a reference to the strand running over this crossing.

This is equivalent to directly constructing StrandRef(this, 1).

Note that upper() and over() are synonyms.

Returns
a reference to the upper strand for this crossing.

◆ useTreeDecomposition()

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

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

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

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

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

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

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

◆ whitehead()

static Link* regina::ExampleLink::whitehead ( )
static

Returns a five-crossing diagram of the Whitehead link.

Returns
a newly constructed link, which must be destroyed by the caller of this routine.

◆ writePACE()

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

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

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

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

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

An example of this text format is as follows:

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

◆ writeTextLong() [1/6]

void regina::Crossing::writeTextLong ( std::ostream &  out) const
inline

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

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

◆ writeTextLong() [2/6]

void regina::ModelLinkGraphNode::writeTextLong ( std::ostream &  out) const
inline

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

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

◆ writeTextLong() [3/6]

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

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

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

◆ writeTextLong() [4/6]

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

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

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

◆ writeTextLong() [5/6]

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

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

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

◆ writeTextLong() [6/6]

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

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

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

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

Reimplemented from regina::Packet.

◆ writeTextShort() [1/6]

void regina::Crossing::writeTextShort ( std::ostream &  out) const
inline

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

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

◆ writeTextShort() [2/6]

void regina::ModelLinkGraphNode::writeTextShort ( std::ostream &  out) const
inline

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

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

◆ writeTextShort() [3/6]

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

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

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

◆ writeTextShort() [4/6]

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

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

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

◆ writeTextShort() [5/6]

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

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

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

◆ writeTextShort() [6/6]

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

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

This must be reimplemented by subclasses.

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

Implements regina::Packet.

◆ writeXMLPacketData()

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

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

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

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

Implements regina::Packet.

◆ writhe()

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

Returns the writhe of this link diagram.

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

Returns
the writhe.

◆ XMLLinkComponentsReader()

regina::XMLLinkComponentsReader::XMLLinkComponentsReader ( Link link)

Creates a new components reader.

The given link should have all its crossings and connections set up, but should have an empty list of components.

Parameters
linkthe link being read.

◆ XMLLinkConnectionsReader()

regina::XMLLinkConnectionsReader::XMLLinkConnectionsReader ( Link link)

Creates a new connections reader.

The given link should have its crossings initialised, but with no connections between them.

Parameters
linkthe link being read.

◆ XMLLinkCrossingsReader()

regina::XMLLinkCrossingsReader::XMLLinkCrossingsReader ( Link link)

Creates a new crossings reader.

The given link should be empty; its crossings will be created by this reader.

Parameters
linkthe link being read.

◆ XMLLinkReader()

regina::XMLLinkReader::XMLLinkReader ( XMLTreeResolver resolver)
inline

Creates a new knot/link reader.

Parameters
resolverthe master resolver that will be used to fix dangling packet references after the entire XML file has been read.

◆ ~Link()

regina::Link::~Link ( )
inline

Destroys this link.

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

◆ ~ModelLinkGraph()

regina::ModelLinkGraph::~ModelLinkGraph ( )
inline

Destroys this graph.

The ModelLinkGraphNode objects contained in this graph will also be destroyed.

◆ ~ModelLinkGraphCells()

regina::ModelLinkGraphCells::~ModelLinkGraphCells ( )
inline

Destroys this cellular decomposition.

◆ ~Tangle()

regina::Tangle::~Tangle ( )
inline

Destroys this tangle.

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

Variable Documentation

◆ homflyAZVarX

const char* regina::Link::homflyAZVarX
static

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

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

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

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

◆ homflyAZVarY

const char* regina::Link::homflyAZVarY
static

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

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

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

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

◆ homflyLMVarX

const char* regina::Link::homflyLMVarX
static

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

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

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

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

◆ homflyLMVarY

const char* regina::Link::homflyLMVarY
static

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

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

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

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

◆ homflyVarX

const char* regina::Link::homflyVarX
static

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

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

◆ homflyVarY

const char* regina::Link::homflyVarY
static

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

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

◆ jonesVar

const char* regina::Link::jonesVar
static

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

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

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

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


Copyright © 1999-2021, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).