insert#

Insert and modify arcs/endpoints in a planar diagram.

These utilities let you: - insert a new arc between two specified endpoint positions at nodes, - insert a loop at a node position, - insert a new leaf (degree-1 vertex) at an endpoint position, - create a parallel arc next to an existing arc.

Notes: - Functions operate in place. - For arc insertions that depend on which endpoint is considered “side A”

versus “side B”, we use an ordered pair (tuple) for the arc rather than a frozenset to keep behavior deterministic.

Functions

insert_arc(k, arc, **attr)

Insert a new arc between two nodes at specified positions.

insert_endpoint(k, target_endpoint, ...)

Insert one endpoint into a node's incidence list (shifting others CCW).

insert_loop(k, endpoint, **attr)

Insert a loop at a node position.

insert_new_leaf(k, target_endpoint[, ...])

Insert a new degree-1 vertex attached at the given endpoint position.

parallelize_arc(k, arc, **attr)

Insert a new arc parallel to an existing arc (on the first endpoint's side).
insert_arc(k, arc, **attr)#

Insert a new arc between two nodes at specified positions.

The function first makes room at each node position (shifting later endpoints CCW), then wires the two new endpoints together.

Parameters:

  • k (PlanarDiagram) – Diagram to modify (in place).

  • arc (tuple[tuple, tuple]) – ((node_a, pos_a), (node_b, pos_b)) — ordered pair of endpoints indicating where to insert the new arc.

  • **attr – Attributes to store on the new endpoints.

Raises:

ValueError – If either target position is invalid for the node.

Return type:

None

Note

We intentionally use an ordered pair rather than a frozenset because the operation is asymmetric (we insert at specific positions on each side).

insert_endpoint(k, target_endpoint, adjacent_endpoint, **attr)#

Insert one endpoint into a node’s incidence list (shifting others CCW).

This is a low-level primitive. It does not automatically update the twin at the other node; it simply places the given adjacent endpoint object into the target position.

Parameters:

  • k (PlanarDiagram) – Diagram to modify (in place).

  • target_endpoint (tuple) – (node, pos) where to place the new endpoint.

  • adjacent_endpoint (tuple | Endpoint) – The endpoint object (or tuple convertible to one) to insert into the node’s incidence list at (node, pos).

  • **attr – Attributes merged into the endpoint at insertion.

Raises:

ValueError – If target node is not a vertex.

Return type:

None

insert_new_leaf(k, target_endpoint, new_node_name=None)#

Insert a new degree-1 vertex attached at the given endpoint position.

Parameters:

  • k (PlanarDiagram) – Diagram to modify (in place).

  • target_endpoint (tuple) – (node, pos) where the new leaf edge attaches.

  • new_node_name (str | None) – Optional explicit name; if omitted, a fresh name is created.

Returns:

The name of the newly created vertex.

Return type:

str

insert_loop(k, endpoint, **attr)#

Insert a loop at a node position.

Creates two new opposite endpoints that connect to each other and lie in consecutive positions around the given node.

Parameters:

  • k (PlanarDiagram) – Diagram to modify (in place).

  • endpoint (tuple | Endpoint) – (node, pos) or an Endpoint.

  • **attr – Endpoint attributes to set on both half-edges.

Raises:

ValueError – If target node is not a vertex.

Return type:

None

parallelize_arc(k, arc, **attr)#

Insert a new arc parallel to an existing arc (on the first endpoint’s side).

The new arc is inserted at position pos_a + 1 at the first endpoint and at pos_b at the second endpoint, effectively drawing a parallel strand.

Parameters:

  • k (PlanarDiagram) – Diagram to modify (in place).

  • arc (tuple[tuple, tuple]) – ((node_a, pos_a), (node_b, pos_b)) – ordered existing arc endpoints.

  • **attr – Attributes for the new arc endpoints.

Raises:

  • NotImplementedError – If the arc is a loop.

  • ValueError – If either endpoint node is not a Vertex.

Return type:

None