canonical#

Putting a diagram into its canonical form.

Given a PlanarDiagram, this module computes a canonical representative by relabeling nodes via a CCW BFS strategy from carefully chosen starting endpoints (min-degree nodes with a minimal neighbor sequence). Disjoint components are canonicalized independently and reassembled in canonical order.

canonical(k)#

Compute the canonical form of an unoriented planar diagram.

Strategy:

  1. If the diagram is disconnected, canonicalize each component and reassemble in canonical order.

  2. Choose starting endpoints among nodes with minimal degree and minimal neighbor-sequence; run CCW BFS to produce a relabeling.

  3. For each start, relabel, then canonically permute node endpoints so the first visited position becomes canonical; keep the lexicographically minimal diagram among all starts.

Warning

Canonical form may be ambiguous for diagrams containing degree-2 vertices.

Parameters:

k (PlanarDiagram | set | list | tuple | Iterable[PlanarDiagram]) – A PlanarDiagram or a collection (set/list/tuple/iterable) thereof.

Returns:

The canonical PlanarDiagram, or a collection with each element canonicalized.

Return type:

PlanarDiagram | set | list | tuple

Example

>>> import knotpy as kp
>>> k = kp.from_pd_notation("[1,4,2,5], [3,6,4,1], [5,2,6,3]")
>>> k
Diagram a → X(b3 b2 c1 c0), b → X(c3 c2 a1 a0), c → X(a3 a2 b1 b0)
>>> k_canonical = kp.canonical(k)
>>> k_canonical
Diagram a → X(b3 b2 c3 c2), b → X(c1 c0 a1 a0), c → X(b1 b0 a3 a2)
>>> k_canonical == kp.knot("3_1")
True
Raises:

  • TypeError – If a non-diagram is provided.

  • ValueError – If the input diagram is not connected when expected.

Parameters:

k (PlanarDiagram | set | list | tuple | Iterable[PlanarDiagram])

Return type:

PlanarDiagram | set | list | tuple

canonical_generator(diagrams)#

Yield canonical forms for a stream of diagrams.

Parameters:

diagrams (Iterable[PlanarDiagram])