planardiagram#

Module Attributes

`Diagram`	Union of knot diagram types used across KnotPy.
`DiagramCollection`	Common collection types of diagrams.

Functions

planar_diagram_from_data(incoming_data, ...)

Generate a planar diagram from input data.

Classes

`OrientedPlanarDiagram`([incoming_diagram_data])	Planar diagram with orientation enabled.
`PlanarDiagram`([incoming_diagram_data])	Planar diagram for spatial graphs, knots, links, and related structures.

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]

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.

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

Bases: PlanarDiagram

Planar diagram with orientation enabled.

Parameters:

incoming_diagram_data (Any | None)
attr (Any)

static is_oriented()#

Return whether the diagram is oriented.

Returns:: bool – Always True for OrientedPlanarDiagram.
Return type:: bool

Diagram = knotpy.classes.planardiagram.PlanarDiagram | knotpy.classes.planardiagram.OrientedPlanarDiagram#: Union of knot diagram types used across KnotPy.

DiagramCollection = list[knotpy.classes.planardiagram.PlanarDiagram | knotpy.classes.planardiagram.OrientedPlanarDiagram] | set[knotpy.classes.planardiagram.PlanarDiagram | knotpy.classes.planardiagram.OrientedPlanarDiagram] | tuple[knotpy.classes.planardiagram.PlanarDiagram | knotpy.classes.planardiagram.OrientedPlanarDiagram, ...]#: Common collection types of diagrams.