OrientedPlanarDiagram#

class OrientedPlanarDiagram(incoming_diagram_data=None, **attr)#

Bases: PlanarDiagram

Planar diagram with orientation enabled.

Parameters:
  • incoming_diagram_data (Any | None)

  • attr (Any)

__init__(incoming_diagram_data=None, **attr)#

Initialize a planar diagram.

If no data is provided, an empty diagram is created. Otherwise, the diagram is populated from the provided input.

Parameters:
  • incoming_diagram_data (Any | None) – Data used to construct/populate the diagram, or None.

  • **attr (Any) – Diagram attributes to set (e.g., name, framing).

Return type:

None

Methods

__init__([incoming_diagram_data])

Initialize a planar diagram.

add_crossing(crossing_for_adding, **attr)

Add or update a classical crossing.

add_crossings_from(crossings_for_adding, **attr)

Add or update multiple classical crossings.

add_node(node_for_adding, create_using[, degree])

Add or update a single node.

add_nodes_from(nodes_for_adding[, create_using])

Add or update multiple nodes.

add_vertex(vertex_for_adding[, degree])

Add or update a vertex.

add_vertices_from(vertices_for_adding, **attr)

Add or update multiple vertices.

add_virtual_crossing(crossing_for_adding, **attr)

Add or update a virtual crossing.

add_virtual_crossings_from(...)

Add or update multiple virtual crossings.

clear()

Remove all nodes and attributes from the diagram.

convert_node(node_for_converting, node_type)

Convert a node's concrete type (e.g., vertex → crossing).

convert_nodes(nodes_for_converting, node_type)

Convert multiple nodes to a given concrete type.

copy([copy_using])

Return a shallow copy of the diagram.

degree(node)

Return a node's degree.

endpoint_from_pair(endpoint_pair)

Return the endpoint instance given a pair description.

is_framed()

Return whether the diagram is framed.

is_frozen()

Return whether the diagram is frozen.

is_locked()

Return whether the diagram is frozen.

is_oriented()

Return whether the diagram is oriented.

permute_node(node, permutation)

Permute positions of a node's endpoints.

relabel_nodes(mapping)

Relabel nodes using a (possibly partial) mapping.

remove_arc(arc_for_removing)

Remove an arc by removing its two endpoints.

remove_arcs_from(arcs_for_removing)

Remove multiple arcs.

remove_endpoint(endpoint_for_removal)

Remove a single endpoint and adjust neighbor positions.

remove_endpoints_from(endpoints_for_removal)

Remove multiple endpoints safely (order-aware).

remove_node(node_for_removing[, ...])

Remove a node (optionally removing incident endpoints).

remove_nodes_from(nodes_for_removal[, ...])

Remove multiple nodes.

set_arc(arc_for_setting, **attr)

Set an arc (pair of endpoints), setting each endpoint to the other.

set_arcs_from(arcs_for_adding, **attr)

Set multiple arcs, optionally parsing from a simple string syntax.

set_endpoint(endpoint_for_setting, ...[, ...])

Set an endpoint to the specified adjacent endpoint, updating attributes.

sign(crossing)

Return the sign of a crossing.

twin(endpoint)

Return the opposite endpoint (twin) of an endpoint.

Attributes

arcs

Return a view of arcs (pairs of endpoints).

crossings

Return a view of all classical crossings.

endpoints

Return a view of endpoints.

faces

Return a view of faces (regions enclosed by arcs).

framing

Return the blackboard framing.

name

Return the diagram name identifier.

nodes

Return a view of the diagram's nodes, providing adjacency information.

number_of_arcs

Return the number of arcs.

number_of_crossings

Return the number of classical crossings.

number_of_endpoints

Return the number of endpoints.

number_of_nodes

Return the number of nodes.

number_of_vertices

Return the number of vertices.

number_of_virtual_crossings

Return the number of virtual crossings.

vertices

Return a view of all vertices.

virtual_crossings

Return a view of all virtual crossings.

static is_oriented()#

Return whether the diagram is oriented.

Returns:

bool – Always True for OrientedPlanarDiagram.

Return type:

bool

add_crossing(crossing_for_adding, **attr)#

Add or update a classical crossing.

Parameters:
  • crossing_for_adding (Hashable) – Crossing identifier (hashable).

  • **attr (object) – Additional attributes (e.g., color, weight).

Return type:

None

add_crossings_from(crossings_for_adding, **attr)#

Add or update multiple classical crossings.

Parameters:
  • crossings_for_adding (Iterable[Hashable]) – Iterable of crossing identifiers.

  • **attr (Any) – Additional attributes for crossings.

Return type:

None

add_node(node_for_adding, create_using, degree=None, **attr)#

Add or update a single node.

Parameters:
  • node_for_adding (Hashable) – Node identifier (hashable).

  • create_using (type) – Node class to construct (e.g., Vertex or Crossing).

  • degree (int | None) – Degree of the node (optional).

  • **attr (Any) – Additional attributes to store on the node.

Raises:
  • TypeError – If create_using is not a type.

  • ValueError – If node_for_adding is None.

  • NotImplementedError – If attempting to change an existing node’s concrete type.

Return type:

None

add_nodes_from(nodes_for_adding, create_using=None, **attr)#

Add or update multiple nodes.

Parameters:
  • nodes_for_adding (Iterable[Hashable] | dict[Hashable, Node]) – Iterable of node identifiers or mapping to existing node instances.

  • create_using (type | None) – Node class used when creating from identifiers.

  • **attr (Any) – Additional attributes applied to created/updated nodes.

Return type:

None

add_vertex(vertex_for_adding, degree=None, **attr)#

Add or update a vertex.

Parameters:
  • vertex_for_adding (Hashable) – Vertex identifier.

  • degree (int | None) – Optional vertex degree.

  • **attr (Any) – Additional attributes.

Return type:

None

add_vertices_from(vertices_for_adding, **attr)#

Add or update multiple vertices.

Parameters:
  • vertices_for_adding (Iterable[Hashable]) – Iterable of vertex identifiers.

  • **attr (object) – Additional attributes applied to each vertex.

Return type:

None

add_virtual_crossing(crossing_for_adding, **attr)#

Add or update a virtual crossing.

Parameters:
  • crossing_for_adding (Hashable) – Crossing identifier (hashable).

  • **attr (object) – Additional attributes.

Return type:

None

add_virtual_crossings_from(crossings_for_adding, **attr)#

Add or update multiple virtual crossings.

Parameters:
  • crossings_for_adding (Iterable[Hashable]) – Iterable of crossing identifiers.

  • **attr (object) – Additional attributes applied to each virtual crossing.

Return type:

None

property arcs: ArcView#

Return a view of arcs (pairs of endpoints).

Returns:

ArcView – View of diagram arcs.

clear()#

Remove all nodes and attributes from the diagram.

Return type:

None

convert_node(node_for_converting, node_type)#

Convert a node’s concrete type (e.g., vertex → crossing).

Parameters:
  • node_for_converting (Hashable) – Node identifier.

  • node_type (type) – Target node class (e.g., Crossing).

Return type:

None

convert_nodes(nodes_for_converting, node_type)#

Convert multiple nodes to a given concrete type.

Parameters:
  • nodes_for_converting (Iterable[Hashable]) – Iterable of node identifiers.

  • node_type (type) – Target node class (e.g., Crossing).

Return type:

None

copy(copy_using=None, **attr)#

Return a shallow copy of the diagram.

Serves for converting, e.g., oriented to unoriented diagrams.

Parameters:
  • copy_using (Optional[type[PlanarDiagram]]) – Concrete diagram type to create; defaults to type(self).

  • attr (Any)

Returns:

PlanarDiagram – New diagram instance with duplicated structure and attributes.

Return type:

PlanarDiagram

property crossings: FilteredNodeView#

Return a view of all classical crossings.

Returns:

FilteredNodeView – Filtered node view containing only classical crossings.

degree(node)#

Return a node’s degree.

Parameters:

node (Hashable) – Node identifier.

Returns:

int – Degree of the node.

Return type:

int

endpoint_from_pair(endpoint_pair)#

Return the endpoint instance given a pair description.

If the second component is a descriptive string for a crossing endpoint (e.g., "over ingoing"), this resolves to the appropriate endpoint.

Parameters:

endpoint_pair (Endpoint | tuple[Hashable, int | str]) – Endpoint instance or pair (node, position_or_description).

Returns:

Endpoint – Resolved endpoint instance.

Raises:

ValueError – If description is invalid or node is not a crossing.

Return type:

Endpoint

property endpoints: EndpointView#

Return a view of endpoints.

Returns:

EndpointView – View of all endpoints in the diagram.

property faces: FaceView#

Return a view of faces (regions enclosed by arcs).

Returns:

FaceView – View of diagram faces.

property framing: int | None#

Return the blackboard framing.

Returns:

Optional[int] – Framing number or None if unframed.

is_framed()#

Return whether the diagram is framed.

Returns:

boolTrue if framed, otherwise False.

Return type:

bool

is_frozen()#

Return whether the diagram is frozen.

Returns:

boolTrue if frozen; otherwise False.

Return type:

bool

is_locked()#

Return whether the diagram is frozen.

Returns:

boolTrue if frozen; otherwise False.

Return type:

bool

property name: str#

Return the diagram name identifier.

Returns:

str – Diagram name (empty if not set).

property nodes: NodeView#

Return a view of the diagram’s nodes, providing adjacency information.

Returns:

NodeView – View of nodes backed by the internal mapping.

property number_of_arcs: int#

Return the number of arcs.

Returns:

int – Number of arcs (half the number of endpoints).

property number_of_crossings: int#

Return the number of classical crossings.

Returns:

int – Number of crossings.

property number_of_endpoints: int#

Return the number of endpoints.

Returns:

int – Number of endpoints over all nodes.

property number_of_nodes: int#

Return the number of nodes.

Returns:

int – Number of nodes in the diagram.

property number_of_vertices: int#

Return the number of vertices.

Returns:

int – Number of vertices.

property number_of_virtual_crossings: int#

Return the number of virtual crossings.

Returns:

int – Number of virtual crossings.

permute_node(node, permutation)#

Permute positions of a node’s endpoints.

If permutation = {0: 0, 1: 2, 2: 3, 3: 1} (or a list/tuple with these images), and the CCW endpoints are [a, b, c, d], the new endpoints become [a, d, b, c].

Parameters:
  • node (Hashable) – Node whose endpoints should be permuted.

  • permutation (dict[int, int] | Sequence[int]) – Mapping or sequence describing the new positions.

Return type:

None

Notes

Endpoint attributes are preserved via set_endpoint. Loops may require special care.

relabel_nodes(mapping)#

Relabel nodes using a (possibly partial) mapping.

Parameters:

mapping (dict[Hashable, Hashable]) – Node-identifier mapping. Unmapped nodes keep original identifiers.

Return type:

None

remove_arc(arc_for_removing)#

Remove an arc by removing its two endpoints.

Parameters:

arc_for_removing (tuple[Endpoint | tuple[Hashable, int], Endpoint | tuple[Hashable, int]]) – Tuple (v_endpoint, u_endpoint).

Return type:

None

remove_arcs_from(arcs_for_removing)#

Remove multiple arcs.

Parameters:

arcs_for_removing (Iterable[tuple[Endpoint | tuple[Hashable, int], Endpoint | tuple[Hashable, int]]]) – Iterable of endpoint pairs to remove.

Return type:

None

remove_endpoint(endpoint_for_removal)#

Remove a single endpoint and adjust neighbor positions.

Parameters:

endpoint_for_removal (Endpoint | tuple[Hashable, int]) – Endpoint instance or pair (node, position).

Return type:

None

remove_endpoints_from(endpoints_for_removal)#

Remove multiple endpoints safely (order-aware).

Parameters:

endpoints_for_removal (Iterable[Endpoint | tuple[Hashable, int]]) – Iterable of endpoint instances or pairs.

Return type:

None

remove_node(node_for_removing, remove_incident_endpoints=True)#

Remove a node (optionally removing incident endpoints).

Parameters:
  • node_for_removing (Hashable) – Node identifier to remove.

  • remove_incident_endpoints (bool) – If False, leaves dangling endpoints (breaks planarity).

Returns:

PlanarDiagram – The diagram (mutated).

Return type:

PlanarDiagram

remove_nodes_from(nodes_for_removal, remove_incident_endpoints=True)#

Remove multiple nodes.

Parameters:
  • nodes_for_removal (Iterable[Hashable]) – Iterable of node identifiers.

  • remove_incident_endpoints (bool) – If False, leaves dangling endpoints.

Return type:

None

set_arc(arc_for_setting, **attr)#

Set an arc (pair of endpoints), setting each endpoint to the other.

Parameters:
  • arc_for_setting (tuple[Endpoint | tuple[Hashable, int], Endpoint | tuple[Hashable, int]]) – Tuple (v_endpoint, u_endpoint) each as Endpoint or pair.

  • **attr (Any) – Additional attributes to apply to the endpoints.

Return type:

None

set_arcs_from(arcs_for_adding, **attr)#

Set multiple arcs, optionally parsing from a simple string syntax.

Example string: "a1b4,c2d3"—also creates missing vertices when needed.

Parameters:
  • arcs_for_adding (Iterable[tuple[Endpoint | tuple[Hashable, int], Endpoint | tuple[Hashable, int]]] | str) – Iterable of endpoint pairs or a string in the simple syntax.

  • **attr (Any) – Additional attributes to apply.

Return type:

None

set_endpoint(endpoint_for_setting, adjacent_endpoint, create_using=<class 'knotpy.classes.endpoint.Endpoint'>, **attr)#

Set an endpoint to the specified adjacent endpoint, updating attributes.

Parameters:
  • endpoint_for_setting (Endpoint | tuple[Hashable, int]) – Endpoint instance or pair (node, position) to modify.

  • adjacent_endpoint (Endpoint | tuple[Hashable, int]) – Endpoint instance or pair (node, position) to set as the twin.

  • create_using (type) – Endpoint class to construct if tuples are provided. If an instance is given, its concrete type is used and attributes copied.

  • **attr (Any) – Additional attributes for the adjacent endpoint.

Raises:
  • TypeError – If create_using is not a type.

  • ValueError – If orientation constraints are violated.

Return type:

None

sign(crossing)#

Return the sign of a crossing.

Parameters:

crossing (Hashable) – Crossing identifier.

Returns:

int – Crossing sign (usually +1 or -1).

Return type:

int

twin(endpoint)#

Return the opposite endpoint (twin) of an endpoint.

Parameters:

endpoint (Endpoint | tuple[Hashable, int]) – Endpoint instance or pair (node, position).

Returns:

Endpoint – The twin endpoint instance.

Return type:

Endpoint

property vertices: FilteredNodeView#

Return a view of all vertices.

Returns:

FilteredNodeView – Filtered node view containing only vertices.

property virtual_crossings: FilteredNodeView#

Return a view of all virtual crossings.

Returns:

FilteredNodeView – Filtered node view containing only virtual crossings.