PlanarDiagram#

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

Bases: _CrossingDiagram, _VertexDiagram, _VirtualCrossingDiagram

Planar diagram for spatial graphs, knots, links, and related structures.

The diagram holds nodes (vertices/crossings), endpoints (incidences of nodes), arcs (pairs of endpoints), and faces (regions). Many of these are derived views over the core _nodes structure and cached lazily.

Parameters:

incoming_diagram_data (Any | None)
attr (Any)

_nodes#

Internal mapping from node identifiers to node instances.

Type:: dict[Hashable, Node]

attr#

Diagram-level attributes (e.g., name, framing, meta).

Type:: dict[str, 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.

clear()#

Remove all nodes and attributes from the diagram.

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 nodes: NodeView#

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

Returns:: NodeView – View of nodes backed by the internal mapping.

property endpoints: EndpointView#

Return a view of endpoints.

Returns:: EndpointView – View of all endpoints in the diagram.

property arcs: ArcView#

Return a view of arcs (pairs of endpoints).

Returns:: ArcView – View of diagram arcs.

property faces: FaceView#

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

Returns:: FaceView – View of diagram faces.

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_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_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

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.

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

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

degree(node)#

Return a node’s degree.

Parameters:: node (Hashable) – Node identifier.
Returns:: int – Degree of the node.
Return type:: int

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

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

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

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

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

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

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

static is_oriented()#

Return whether the diagram is oriented.

Returns:: bool – False for the base PlanarDiagram.
Return type:: bool

property number_of_nodes: int#

Return the number of nodes.

Returns:: int – Number of nodes in the diagram.

property number_of_crossings: int#

Return the number of classical crossings.

Returns:: int – Number of crossings.

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.

property number_of_endpoints: int#

Return the number of endpoints.

Returns:: int – Number of endpoints over all nodes.

property number_of_arcs: int#

Return the number of arcs.

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

is_framed()#

Return whether the diagram is framed.

Returns:: bool – True if framed, otherwise False.
Return type:: bool

property name: str#

Return the diagram name identifier.

Returns:: str – Diagram name (empty if not set).

property framing: int | None#

Return the blackboard framing.

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

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_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 crossings: FilteredNodeView#

Return a view of all classical crossings.

Returns:: FilteredNodeView – Filtered node view containing only classical crossings.

is_frozen()#

Return whether the diagram is frozen.

Returns:: bool – True if frozen; otherwise False.
Return type:: bool

is_locked()#

Return whether the diagram is frozen.

Returns:: bool – True if frozen; otherwise False.
Return type:: bool

sign(crossing)#

Return the sign of a crossing.

Parameters:: crossing (Hashable) – Crossing identifier.
Returns:: int – Crossing sign (usually +1 or -1).
Return type:: int

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.