The Components module¶

Crossings: The primary building blocks¶

A simple example: Creating a trefoil diagram¶

The following code excerpt demonstrates how you might use Crossing objects to manually construct a PlanarDiagram object in Python:

from libpl.pdcode import PlanarDiagram
print "Hello"

The Crossing class¶

class libpl.pdcode.components.Crossing¶

A crossing, which holds four edges in positions and an orientation.

Crossing data is the most important piece of data in a PlanarDiagram. A full diagram object can be built from crossing data alone (although orientations of components may differ).

Once you are finished setting any of the edges, you must call regenerate() on the parent so that sanity can be checked and faces and components regenerated.

Accessing crossing information

Crossings support two methods of viewing their child edge data;

Crossings X support being accessed as if they were lists; X[i] retrieves the Edge attached at position i. This method takes into account that vertices are cyclical, but does not support assignment.

The property edges is a direct-memory view of edge indices attached to this crossing. It is possible to change these indices, but the parent must be regenerated and validity checked manually after doing this.

adjacent(pos) → Crossing, int position¶: Returns the crossing and position to which the edge at pos points.

edges¶

A memory view of the indices of the edges which connect to this crossing.

Indices can be changed, but you have to be careful and regenerate/validity check the diagram after this.

If you want objects instead of indices, access this Crossing like a sequence instead.

faces¶: A tuple of the indices of the faces around this vertex, in counterclockwise order.

get_faces() → tuple of Faces¶: Return the faces on which this crossing is a vertex, in clockwise order.

index¶: The index by which this crossing is known in the parent.

overstrand() → Edge incoming, Edge outgoing¶

Return Edge objects which are the incoming and outgoing edges for the strand which passes over this crossing.

If you want indices instead of objects, use overstrand_indices().

overstrand_indices() → in_index, out_index¶

Return indices corresponding to the incoming and outgoing edges for the strand which passes over this crossing.

If you want objects instead of indices, use overstrand().

overstrand_pos() → in_pos, out_pos¶: Return indices around this crossing corresponding to the incoming and outgoing edges for the strand which passes over this crossing.

parent¶: The PlanarDiagram to which this crossing belongs.

sign¶

The orientation of this crossing. The convention used to determine sign is this:

Positive crossing: (upper tangent vector) \(\times\) (lower tangent vector) points OUT of screen:

     ^
     |
----------->
     |
     |

Negative crossing: (upper tangent vector) \(\times\) (lower tangent vector) points INTO screen:

     ^
     |
-----|----->
     |
     |

You often simply want to know which of the strands (0-2) or (1-3) is on top. There are several cases, because it depends BOTH on the sign of the crossing and the orientation of the strands. It’s recommended to use the methods overstrand() and understrand() to determine which is which. Also, the methods overstrand_pos() and understrand_pos() return the position in this crossing (that is, a number in 0..3) of the incoming and outgoing edges of the strand going over at this crossing.

toggle_sign(self)¶: Switches the sign of the crossing to be positive if it was negative, or negative if it was positive. Has no effect on a crossing which is unsigned.

understrand() → Edge incoming, Edge outgoing¶

Return Edge objects which are the incoming and outgoing edges for the strand which passes under this crossing.

If you want indices instead of objects, use understrand_indices().

understrand_indices() → in_index, out_index¶

Return indices corresponding to the incoming and outgoing edges for the strand which passes under this crossing.

If you want objects instead of indices, use understrand().

understrand_pos() → in_pos, out_pos¶: Return indices around this crossing corresponding to the incoming and outgoing edges for the strand which passes under this crossing.

Edges¶

class libpl.pdcode.components.Edge¶

An oriented edge, joining two vertices tail -> head.

Once you are finished setting any of the properties head, headpos, tail, and tailpos, you must call regenerate() on the parent so that sanity can be checked and faces and components regenerated.

component_index_pos() → component index, edge pos¶: Returns the index of the component on which this edge resides and this edge’s position on that component.

component_pos() → Component, edge pos¶: Returns the Component on which this edge resides and this edge’s position on that component. If you just want the index of the component, use component_index_pos()

face_index_pos() → [pos_face, pos], [neg_face, pos]¶: Returns the face indices on which this edge resides and this edge’s position on those faces.

face_pos() → [Face plus, pos], [Face minus, pos]¶: Returns the Faces on which this edge resides and this edge’s position on that face. If you just want the indices of the faces, use face_index_pos()

head¶: The index of the crossing towards which this edge points.

head_tuple¶

A tuple (vertex, pos) describing where this edge points.

The position is an index [0..3] in crossing record of head vertex.

headpos¶: The position in the crossing towards which this edge points.

index¶: The index by which this edge is known in the parent.

next_crossing() → Crossing¶: Return the Crossing towards which this edge points

next_edge() → Edge¶: Return the next Edge along the component

oriented(sign) → Edge¶

Returns a copy of original edge if sign is POS_ORIENTATION, or a new reversed edge if sign is NEG_ORIENTATION.

The Edge returned is not connected to any PlanarDiagram until it is attached.

parent¶: The PlanarDiagram to which this edge belongs.

plug_head(Crossing x, pos)¶

Redirect the head of this edge to point to x[pos].

Parameters:	x (Crossing) – The crossing to connect this edge to pos (int) – The position in [0..3] of the `Crossing` `x` to connect this edge to.
Raises:	Exception – If this edge is either not part of a `PlanarDiagram`, or connected to a different `PlanarDiagram` than the `Crossing` `x`.

plug_tail(Crossing x, pos)¶

Redirect the tail of this edge to point from x[pos].

Parameters:	x (Crossing) – The crossing to connect this edge to pos (int) – The position in [0..3] of the `Crossing` `x` to connect this edge to.
Raises:	Exception – If this edge is either not part of a `PlanarDiagram`, or connected to a different `PlanarDiagram` than the `Crossing` `x`.

prev_crossing() → Crossing¶: Return the Crossing from which this edge originates.

prev_edge() → Edge¶: Return the previous Edge along the component

reorient(sign)¶: Flips the edge if sign is NEG_ORIENTATION.

swap_head(Edge other, head_or_tail)¶

Swap the head of this edge with the head or tail of edge other.

Parameters:	other (Edge) – the other edge with whom to swap head_or_tail – Either `NEG_ORIENTATION` or `POS_ORIENTATION`, which determines whether to swap the head of this edge with the tail or head of `other`, respectively.
Raises:	Exception – If head_or_tail is not a valid orientation choice, or this edge is connected to a different parent than `other`

swap_tail(Edge other, head_or_tail)¶

Swap the tail of this edge with the head or tail of edge other.

Parameters:	other (Edge) – the other edge with whom to swap head_or_tail – Either `NEG_ORIENTATION` or `POS_ORIENTATION`, which determines whether to swap the tail of this edge with the tail or head of `other`, respectively.
Raises:	Exception – If head_or_tail is not a valid orientation choice, or this edge is connected to a different parent than `other`

tail¶: The index of the crossing from which this edge leaves.

tail_tuple¶

A tuple (vertex, pos) describing where this edge leaves.

The position is an index [0..3] in crossing record of tail vertex.

tailpos¶: The position in the crossing from which this edge leaves.

Link components¶

class libpl.pdcode.components.Component¶

A component of a diagram.

A component is an oriented cycle of edges in its parent diagram, formed by proceeding directly across each crossing to the following edge. If a diagram has only one Component, it is a knot diagram.

edge¶: A tuple of edge indices of which this component consists

index¶: The index by which this component is known in the parent.

nedges¶: The number of edges in this component. Equivalent to len(cmp).

parent¶: The PlanarDiagram to which this component belongs.

Faces¶

class libpl.pdcode.components.Face¶

A face of a diagram.

A face is an oriented cycle of edges in its parent diagram, formed by turning at each corner of a vertex. Each face has the topology of a disk.

edges¶

A tuple of the indices of the edges around this face. The edges are in counterclockwise order around the face.

If you want to access the Python objects, use this Face object like a sequence instead (e.g. face[4] or for edge in face:).

get_vertices() -> (Crossing[, Crossing, …])¶: A tuple of Crossings around this face in counterclockwise order. The first crossing is the one immediately before the first edge in this face.

index¶: The index by which this face is known in the parent.

nedges¶: The number of edges in this face

parent¶: The PlanarDiagram to which this face belongs.

signs¶: A tuple of the signs of the edges around this face. The edges are in counterclockwise order around the face.

vertices¶: A tuple of the crossing indices around this face in counterclockwise order.