knit_graphs.Knit_Graph module

The graph structure used to represent knitted objects.

This module contains the main Knit_Graph class which serves as the central data structure for representing knitted fabrics. It manages the relationships between loops, yarns, and structural elements like courses and wales.

class Knit_Graph[source]

Bases: Directed_Loop_Graph[LoopT, Pull_Direction]

A representation of knitted structures as connections between loops on yarns.

The Knit_Graph class is the main data structure for representing knitted fabrics. It maintains a directed graph of loops connected by stitch edges, manages yarn relationships, and provides methods for analyzing the structure of the knitted fabric including courses, wales, and cable crossings.

__init__() → None[source]: Initialize an empty knit graph with no loops or yarns.

property last_loop: LoopT | None

Get the most recently added loop in the graph.

Returns:: The last loop added to the graph, or None if no loops have been added.
Return type:: Loop | None

property stitch_iter: Iterator[tuple[LoopT, LoopT, Pull_Direction]]

Returns:: Iterator over the edges and edge-data in the graph.
Return type:: Iterator[tuple[LoopT, LoopT, Pull_Direction]]

Notes

No guarantees about the order of the edges.

get_pull_direction(parent: LoopT | int, child: LoopT | int) → Pull_Direction[source]

Get the pull direction of the stitch edge between parent and child loops.

Parameters:

parent (Loop | int) – The parent loop of the stitch edge.
child (Loop | int) – The child loop of the stitch edge.

Returns:

The pull direction of the stitch-edge between the parent and child.

Return type:

Pull_Direction

add_crossing(left_loop: LoopT, right_loop: LoopT, crossing_direction: Crossing_Direction) → None[source]

Add a cable crossing between two loops with the specified crossing direction.

Parameters:

left_loop (Loop) – The loop on the left side of the crossing.
right_loop (Loop) – The loop on the right side of the crossing.
crossing_direction (Crossing_Direction) – The direction of the crossing (over, under, or none) between the loops.

add_loop(loop: LoopT) → None[source]

Add a loop to the knit graph as a node.

Parameters:: loop (Loop) – The loop to be added as a node in the graph. If the loop’s yarn is not already in the graph, it will be added automatically.

remove_loop(loop: LoopT | int) → None[source]

Remove the given loop from the knit graph. :param loop: The loop or loop_id to be removed. :type loop: Loop | int

Raises:: KeyError – If the loop is not in the knit graph.

add_yarn(yarn: Yarn[LoopT]) → None[source]

Add a yarn to the graph without adding its loops.

Parameters:: yarn (Yarn[LoopT]) – The yarn to be added to the graph structure. This method assumes that loops do not need to be added separately.

connect_loops(parent_loop: LoopT, child_loop: LoopT, pull_direction: Pull_Direction = BtF, stack_position: int | None = None) → None[source]

Create a stitch edge by connecting a parent and child loop.

Parameters:

parent_loop (Loop) – The parent loop to connect to the child loop.
child_loop (Loop) – The child loop to connect to the parent loop.
pull_direction (Pull_Direction) – The direction the child is pulled through the parent. Defaults to Pull_Direction.BtF (knit stitch).
stack_position (int | None, optional) – The position to insert the parent into the child’s parent stack. If None, adds on top of the stack. Defaults to None.

Raises:

KeyError – If either the parent_loop or child_loop is not already in the knit graph.

get_wales_ending_with_loop(last_loop: LoopT) → set[Wale[LoopT]][source]

Get all wales (vertical columns of stitches) that end at the specified loop.

Parameters:: last_loop (Loop) – The last loop of the joined set of wales.
Returns:: The set of wales that end at this loop.
Return type:: set[Wale[LoopT]]

get_terminal_wales() → dict[LoopT, list[Wale]][source]

Get wale groups organized by their terminal loops.

Returns:: Dictionary mapping terminal loops to list of wales that terminate that wale.
Return type:: dict[Loop, list[Wale]]

get_courses() → list[Course[LoopT]][source]

Get all courses (horizontal rows) in the knit graph in chronological order.

Returns:: A list of courses representing horizontal rows of loops.
Return type:: list[Course[LoopT]

get_wale_groups() → set[Wale_Group][source]

Get wale groups organized by their terminal loops.

Returns:: The set of wale-groups that lead to the terminal loops of this graph. Each wale group represents a collection of wales that end at the same terminal loop.
Return type:: set[Wale_Group]

classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

__contains__(item: LoopT | int | tuple[LoopT | int, LoopT | int]) → bool

Parameters:: item (LoopT | int | tuple[LoopT | int, LoopT | int]) – The loop, loop-id, or a pair of loops in a directed edge to search for.
Returns:: True if the graph contains the given loop or edge.
Return type:: bool

__getitem__(item: int | tuple[LoopT | int, LoopT | int]) → LoopT | EdgeT

Parameters:: item (int | tuple[LoopT | int, LoopT | int]) – The id of the loop or the pair of loops that form an edge in the graph.
Returns:: The loop associated with the given id. EdgeT: The edge data associated with the given pair of loops/ loop_ids.
Return type:: LoopT
Raises:: KeyError – The given loop or edge does not exist in the graph.

__iter__() → Iterator[LoopT]

Returns:: Iterator over all the loops in the graph.
Return type:: Iterator[LoopT]

Notes

No guarantees about order of loops. Expected to be insertion order.

__len__() → int

Returns:: The number of loops in the graph.
Return type:: int

add_edge(u: LoopT | int, v: LoopT | int, edge_data: EdgeT) → None

Connect the given loop u to the loop v with the given edge data. :param u: The loop to connect to. :type u: LoopT | int :param v: The loop to connect to. :type v: LoopT | int :param edge_data: The edge data to associate with the connection. :type edge_data: EdgeT

Raises:: KeyError – Either of the given loops does not exist in the graph.

ancestors(loop: LoopT) → set[LoopT]

Parameters:: loop (LoopT) – The loop to get the ancestors of from the graph.
Returns:: The ancestors of the given loop.
Return type:: set[LoopT]

property contains_loops: bool: Returns: bool: True if the graph has at least one loop, False otherwise.

dfs_edges(loop: LoopT) → Iterator[tuple[LoopT, LoopT]]

Parameters:: loop (LoopT) – The loop to start iteration over edges from.
Returns:: The depth-first-search ordering of edges starting from the given loop.

dfs_preorder_loops(loop: LoopT) → Iterator[LoopT]

Parameters:: loop (LoopT) – The loop to start iteration from.
Returns:: The depth-first-search ordering of loops in the graph starting from the given loop.
Return type:: Iterator[LoopT]

property edge_count: int: Returns: int: The number of edges in the graph.

property edge_iter: Iterator[tuple[LoopT, LoopT, EdgeT]]

Returns:: Iterator over the edges and edge-data in the graph.
Return type:: Iterator[tuple[LoopT, LoopT, EdgeT]]

Notes

No guarantees about the order of the edges.

get_child_loop(loop: LoopT) → LoopT | None

Parameters:: loop (LoopT) – The loop to look for a child loop from.
Returns:: The child loop if one exists, or None if no child loop is found.
Return type:: LoopT | None

get_edge(u: LoopT | int, v: LoopT | int) → EdgeT

Parameters:

u (LoopT | int) – The loop or id of the first loop in the edge.
v (LoopT | int) – The loop or id of the second loop in the edge.

Returns:

The data about the edge from loop u to v.

Return type:

EdgeT

get_loop(loop_id: int) → LoopT

Parameters:: loop_id (int) – The loop id of the loop to get from the graph.
Returns:: The loop node in the graph.
Return type:: LoopT

has_child_loop(loop: LoopT) → bool

Parameters:: loop (Loop) – The loop to check for child connections.
Returns:: True if the loop has a child loop, False otherwise.
Return type:: bool

has_edge(u: LoopT | int, v: LoopT | int) → bool

Parameters:

u (LoopT | int) – The loop or id of the first loop in the edge.
v (LoopT | int) – The loop or id of the second loop in the edge.

Returns:

True if the graph has an edge from loop u to v. False, otherwise.

Return type:

bool

has_loop(loop: int | LoopT) → bool

Parameters:: loop (int | LoopT) – The loop or loop id to check for in the graph.
Returns:: True if the loop id is in the graph. False, otherwise.
Return type:: bool

is_descendant(ancestor: LoopT, descendant: LoopT) → bool

Parameters:

ancestor (LoopT) – The loop to check if it is an ancestor of the other loop.
descendant (LoopT) – The loop to check if it is a descendant of the other loop.

Returns:

True if there is a directed path from the ancestor to the descendant, False otherwise.

Return type:

bool

is_terminal_loop(loop: LoopT) → bool

Parameters:: loop (LoopT) – The loop to check for terminal status.
Returns:: True if the loop has no child loops, False otherwise.
Return type:: bool

property loop_count: int: Returns: int: The number of loops in the graph.

predecessors(loop: int | LoopT) → set[LoopT]

Parameters:: loop (int | LoopT) – The loop to get the predecessors of from the graph.
Returns:: The successors of the loop.
Return type:: set[LoopT]

remove_edge(u: LoopT | int, v: LoopT | int) → None

Removes the edge from loop u to the loop v from the graph. :param u: The loop to connect to. :type u: LoopT | int :param v: The loop to connect to. :type v: LoopT | int

Raises:: KeyError – The given edge does not exist in the graph.

property sorted_loops: list[LoopT]: Returns: list[Loop]: The list of loops in the graph sorted from the earliest formed loop to the latest formed loop.

source_loops(loop: LoopT) → set[LoopT]

Parameters:: loop (LoopT) – The loop to get the sources of.
Returns:: The source loops of the given loop. These are the loops that are the source of all ancestors to the given loop.
Return type:: set[LoopT]

successors(loop: int | LoopT) → set[LoopT]

Parameters:: loop (int | LoopT) – The loop to get the successors of from the graph.
Returns:: The successors of the loop.
Return type:: set[LoopT]

property terminal_loops: Iterator[LoopT]: Returns: Iterator[Loop]: An iterator over all terminal loops in the graph.