knit_graphs.artin_wale_braids.Wale_Group module

Module containing the Wale_Group class and its methods.

This module provides the Wale_Group class which represents a collection of interconnected wales that are joined through decrease operations, forming a tree-like structure of vertical stitch columns.

class Wale_Group(terminal_loop: LoopT, knit_graph: Knit_Graph[LoopT])[source]

Bases: Directed_Loop_Graph[LoopT, Pull_Direction]

A graph structure maintaining relationships between connected wales through decrease operations.

This class represents a collection of wales that are connected through decrease stitches, where multiple wales merge into fewer wales as the knitting progresses upward. It maintains both the wale-to-wale relationships and the individual stitch connections within the group.

wale_graph

A directed graph representing the relationships between wales in this group.

Type:: DiGraph

top_loops

Mapping from the last (top) loop of each wale to the wale itself.

Type:: dict[Loop, Wale]

bottom_loops

Mapping from the first (bottom) loop of each wale to the wale itself.

Type:: dict[Loop, Wale]

__init__(terminal_loop: LoopT, knit_graph: Knit_Graph[LoopT])[source]

Initialize a wale group starting from a terminal wale and building downward.

Parameters:

terminal_loop (Loop) – The terminal loop of this wale-group. All the wales in the group connect up to this loop.
knit_graph (Knit_Graph) – The parent knit graph that contains this wale group.

property terminal_loop: LoopT: Returns: LoopT: The loop that terminates all wales in this group.

get_loops_over_courses() → list[list[LoopT]][source]

Get loops organized by their course (horizontal row) within this wale group.

This method traces through the stitch connections starting from the terminal wale’s top loop and groups loops by their vertical position (course) in the knitted structure.

Returns:: A list where each inner list contains all loops that belong to the same course, ordered from top to bottom courses. Returns empty list if there is no terminal wale.
Return type:: list[list[LoopT]]

__len__() → int[source]

Get the height of the wale group measured as the maximum number of loops from base to terminal.

This method calculates the total length by summing all loops in all wales that can be reached from each bottom wale, returning the maximum total length found.

Returns:: The height of the wale group from the base loops to the tallest terminal, measured in total number of loops.
Return type:: int

__hash__() → int[source]

Returns:: Hash value of the terminal loop of this group.
Return type:: int

Parameters:: item (LoopT | int | tuple[LoopT | int, LoopT | int] | Wale) – The item to check for in the wale group.
Returns:: True if the given loop, loop_id (int), pair of loops, or wale is in this group.
Return type:: bool

__str__() → str[source]

Returns:: The string representation of this wale group.
Return type:: str

__repr__() → str[source]

Returns:: The string representation of this wale group.
Return type:: str

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]): ….

__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.

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.

add_loop(loop: LoopT) → None: Add the given loop to the loop graph. :param loop: The loop to add to the graph. :type loop: LoopT

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.

remove_loop(loop: LoopT | int) → None

Remove the given loop from the graph. :param loop: The loop or id of the loop to remove. :type loop: LoopT | int

Raises:: KeyError – The given loop 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.