knit-graphs 0.0.11__py3-none-any.whl → 0.0.12__py3-none-any.whl

knit_graphs/artin_wale_braids/Wale_Group.py

@@ -5,18 +5,22 @@ This module provides the Wale_Group class which represents a collection of inter
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, cast
+from typing import TYPE_CHECKING, TypeVar
 
 from networkx import DiGraph, dfs_preorder_nodes
 
 from knit_graphs.artin_wale_braids.Wale import Wale
+from knit_graphs.directed_loop_graph import Directed_Loop_Graph
 from knit_graphs.Loop import Loop
+from knit_graphs.Pull_Direction import Pull_Direction
 
 if TYPE_CHECKING:
     from knit_graphs.Knit_Graph import Knit_Graph
 
+LoopT = TypeVar("LoopT", bound=Loop)
 
-class Wale_Group:
+
+class Wale_Group(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.
@@ -24,47 +28,68 @@ class Wale_Group:
 
     Attributes:
         wale_graph (DiGraph): A directed graph representing the relationships between wales in this group.
-        stitch_graph (DiGraph): A directed graph of all individual stitch connections within this wale group.
         top_loops (dict[Loop, Wale]): Mapping from the last (top) loop of each wale to the wale itself.
         bottom_loops (dict[Loop, Wale]): Mapping from the first (bottom) loop of each wale to the wale itself.
     """
 
-    def __init__(self, terminal_loop: Loop, knit_graph: Knit_Graph):
+    def __init__(self, terminal_loop: LoopT, knit_graph: Knit_Graph[LoopT]):
         """Initialize a wale group starting from a terminal wale and building downward.
 
         Args:
             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.
         """
+        super().__init__()
         self.wale_graph: DiGraph = DiGraph()
-        self.stitch_graph: DiGraph = DiGraph()
-        self._knit_graph: Knit_Graph = knit_graph
-        self._terminal_loop: Loop = terminal_loop
-        self.top_loops: dict[Loop, Wale] = {}
-        self.bottom_loops: dict[Loop, Wale] = {}
+        self._knit_graph: Knit_Graph[LoopT] = knit_graph
+        self._terminal_loop: LoopT = terminal_loop
+        self.top_loops: dict[LoopT, Wale] = {}
+        self.bottom_loops: dict[LoopT, Wale] = {}
         self._build_wale_group()
 
     @property
-    def terminal_loop(self) -> Loop:
+    def terminal_loop(self) -> LoopT:
         """
         Returns:
-            Loop: The loop that terminates all wales in this group.
+            LoopT: The loop that terminates all wales in this group.
         """
         return self._terminal_loop
 
+    def get_loops_over_courses(self) -> list[list[LoopT]]:
+        """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:
+            list[list[LoopT]]: 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.
+        """
+        courses: list[list[LoopT]] = []
+        cur_course: list[LoopT] = [self._terminal_loop]
+        while len(cur_course) > 0:
+            courses.append(cur_course)
+            next_course: list[LoopT] = []
+            for loop in cur_course:
+                next_course.extend(self.predecessors(loop))
+            cur_course = next_course
+        return courses
+
     def _build_wale_group(self) -> None:
         full_wales = self._knit_graph.get_wales_ending_with_loop(self._terminal_loop)
         # Build up the stitch graph.
         for wale in full_wales:
-            u_loops: list[Loop] = cast(list[Loop], wale[:-1])
-            v_loops: list[Loop] = cast(list[Loop], wale[1:])
+            u_loops = wale[:-1]
+            v_loops = wale[1:]
             for u, v in zip(u_loops, v_loops, strict=False):
-                self.stitch_graph.add_edge(u, v, pull_direction=self._knit_graph.get_pull_direction(u, v))
+                if u not in self:
+                    self.add_loop(u)
+                if v not in self:
+                    self.add_loop(v)
+                self.add_edge(u, v, self._knit_graph.get_pull_direction(u, v))
         wales_to_split = full_wales
         while len(wales_to_split) > 0:
             wale_to_split = wales_to_split.pop()
             split = False
-            upper_loops = cast(list[Loop], wale_to_split[1:])
+            upper_loops = wale_to_split[1:]
             for (
                 loop
             ) in upper_loops:  # skip first loop in each wale as it may be already connected to a discovered decrease.
@@ -87,24 +112,6 @@ class Wale_Group:
         self.top_loops[wale.last_loop] = wale
         self.bottom_loops[wale.first_loop] = wale
 
-    def get_loops_over_courses(self) -> list[list[Loop]]:
-        """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:
-            list[list[Loop]]: 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.
-        """
-        courses: list[list[Loop]] = []
-        cur_course: list[Loop] = [self._terminal_loop]
-        while len(cur_course) > 0:
-            courses.append(cur_course)
-            next_course = []
-            for loop in cur_course:
-                next_course.extend(self.stitch_graph.predecessors(loop))
-            cur_course = next_course
-        return courses
-
     def __len__(self) -> int:
         """Get the height of the wale group measured as the maximum number of loops from base to terminal.
 
@@ -126,18 +133,18 @@ class Wale_Group:
         """
         return hash(self._terminal_loop)
 
-    def __contains__(self, item: Loop | int | Wale) -> bool:
+    def __contains__(self, item: LoopT | int | tuple[LoopT | int, LoopT | int] | Wale) -> bool:
         """
         Args:
-            item (Loop | int | Wale): The item to check for in the wale group.
+            item (LoopT | int | tuple[LoopT | int, LoopT | int] | Wale): The item to check for in the wale group.
 
         Returns:
-            bool: True if the given loop, loop_id (int), or wale is in this group.
+            bool: True if the given loop, loop_id (int), pair of loops, or wale is in this group.
         """
-        if isinstance(item, (Loop, int)):
-            return item in self.stitch_graph.nodes
-        else:  # isinstance(item, Wale):
+        if isinstance(item, Wale):
             return item in self.wale_graph
+        else:
+            return super().__contains__(item)
 
     def __str__(self) -> str:
         """

knit_graphs/basic_knit_graph_generators.py

@@ -4,30 +4,34 @@ This module provides utility functions for creating common knitting patterns and
 These functions serve as building blocks for testing and demonstration purposes.
 """
 
-from knit_graphs.artin_wale_braids.Crossing_Direction import Crossing_Direction
+from __future__ import annotations
+
+from collections.abc import Sequence
+
 from knit_graphs.Knit_Graph import Knit_Graph
+from knit_graphs.knit_graph_builder import Knit_Graph_Builder
 from knit_graphs.Loop import Loop
 from knit_graphs.Pull_Direction import Pull_Direction
 from knit_graphs.Yarn import Yarn
 
 
-def co_loops(width: int) -> tuple[Knit_Graph, Yarn]:
+def co_loops(width: int) -> tuple[Knit_Graph_Builder[Loop], Knit_Graph[Loop], Yarn[Loop]]:
     """Create a cast-on row of loops forming the foundation for knitting patterns.
 
     Args:
         width (int): The number of loops to create in the cast-on row.
 
     Returns:
-        tuple[Knit_Graph, Yarn]: A tuple containing the knit graph with one course of the specified width and the yarn used to create it.
+        tuple[Knit_Graph_Builder[Loop], Knit_Graph[Loop], Yarn[Loop]: A tuple containing the knit graph builder and its knitgraph with one course of the specified width and the yarn used to create it.
     """
-    knit_graph = Knit_Graph()
-    yarn = Yarn(knit_graph=knit_graph)
+    builder = Knit_Graph_Builder[Loop]()
+    yarn = builder.add_yarn()
     for _ in range(0, width):
-        _loop = yarn.make_loop_on_end()
-    return knit_graph, yarn
+        _loop = builder.tuck(yarn)
+    return builder, builder.knit_graph, yarn
 
 
-def jersey_swatch(width: int, height: int) -> Knit_Graph:
+def jersey_swatch(width: int, height: int) -> Knit_Graph[Loop]:
     """Generate a rectangular knit swatch with all knit stitches in a flat sheet structure.
 
     This creates a basic stockinette/jersey pattern where all stitches are worked as knit stitches from back to front.
@@ -39,19 +43,14 @@ def jersey_swatch(width: int, height: int) -> Knit_Graph:
     Returns:
         Knit_Graph: A knit graph representing a flat rectangular swatch with all knit stitches.
     """
-    knit_graph, yarn = co_loops(width)
-    last_course = list(knit_graph.get_courses()[0])
+    builder, knit_graph, yarn = co_loops(width)
+    last_course: Sequence[Loop] = knit_graph.get_courses()[0]
     for _ in range(0, height):
-        next_course = []
-        for parent_loop in reversed(last_course):
-            child_loop = yarn.make_loop_on_end()
-            knit_graph.connect_loops(parent_loop, child_loop, pull_direction=Pull_Direction.BtF)
-            next_course.append(child_loop)
-        last_course = next_course
+        last_course = [builder.knit(yarn, [parent_loop]) for parent_loop in reversed(last_course)]
     return knit_graph
 
 
-def jersey_tube(tube_width: int, height: int) -> Knit_Graph:
+def jersey_tube(tube_width: int, height: int) -> Knit_Graph[Loop]:
     """Generate a tubular knit structure with all knit stitches worked in the round.
 
     This creates a seamless tube by knitting in the round, where the front and back sections are connected by floats to maintain the circular structure.
@@ -63,33 +62,22 @@ def jersey_tube(tube_width: int, height: int) -> Knit_Graph:
     Returns:
         Knit_Graph: A knit graph representing a seamless tube with all knit stitches.
     """
-    knit_graph, yarn = co_loops(tube_width * 2)
-    last_course = [*knit_graph.get_courses()[0]]
-
-    def _set_tube_floats() -> None:
-        """Internal helper function to set up float connections between front and back of tube."""
-        front_loops = last_course[0:tube_width]
-        back_loops = last_course[tube_width:]
-        for first_front, second_front, back in zip(
-            front_loops[0:-1], front_loops[1:], reversed(back_loops), strict=False
-        ):
-            yarn.add_loop_behind_float(back, first_front, second_front)
-        for first_back, second_back, front in zip(
-            back_loops[0:-1], back_loops[1:], reversed(front_loops), strict=False
-        ):
-            yarn.add_loop_in_front_of_float(front, first_back, second_back)
-
-    _set_tube_floats()
+    builder = Knit_Graph_Builder[Loop]()
+    yarn = builder.add_yarn()
+    front_of_tube = [builder.tuck(yarn) for _ in range(0, tube_width)]
+    back_of_tube = [builder.tuck(yarn) for _ in reversed(front_of_tube)]
     for _ in range(0, height):
-        next_course = [yarn.make_loop_on_end() for _p in last_course]
-        for parent_loop, child_loop in zip(last_course, next_course, strict=False):
-            knit_graph.connect_loops(parent_loop, child_loop, pull_direction=Pull_Direction.BtF)
-        last_course = next_course
-        _set_tube_floats()
-    return knit_graph
+        for fl, bl in zip(front_of_tube[:-1], reversed(back_of_tube[1:]), strict=False):
+            builder.position_float(fl, loops_behind_float=[bl])
+        for fl, bl in zip(reversed(front_of_tube[1:]), back_of_tube[:-1], strict=False):
+            builder.position_float(bl, loops_in_front_of_float=[fl])
+        front_of_tube = [builder.knit(yarn, [fl], Pull_Direction.BtF) for fl in front_of_tube]
+        back_of_tube = [builder.knit(yarn, [bl], Pull_Direction.FtB) for bl in back_of_tube]
 
+    return builder.knit_graph
 
-def kp_rib_swatch(width: int, height: int) -> Knit_Graph:
+
+def kp_rib_swatch(width: int, height: int) -> Knit_Graph[Loop]:
     """Generate a knit-purl ribbing swatch with alternating wales of knit and purl stitches.
 
     This creates a 1x1 ribbing pattern where knit and purl wales alternate, maintaining their stitch type throughout the height of the swatch for a stretchy, textured fabric.
@@ -101,30 +89,19 @@ def kp_rib_swatch(width: int, height: int) -> Knit_Graph:
     Returns:
         Knit_Graph: A knit graph representing a ribbed swatch with alternating knit and purl wales.
     """
-    knit_graph, yarn = co_loops(width)
-    last_course = knit_graph.get_courses()[0]
-    next_course = []
-    next_pull = Pull_Direction.BtF
-    for parent_loop in reversed(last_course):
-        child_loop = yarn.make_loop_on_end()
-        knit_graph.connect_loops(parent_loop, child_loop, pull_direction=next_pull)
-        next_pull = next_pull.opposite()
-        next_course.append(child_loop)
-    last_course = next_course
-    for _ in range(1, height):
-        next_course = []
-        for parent_loop in reversed(last_course):
-            grand_parent = parent_loop.parent_loops[0]
-            parent_pull = knit_graph.get_pull_direction(grand_parent, parent_loop)
-            assert isinstance(parent_pull, Pull_Direction)
-            child_loop = yarn.make_loop_on_end()
-            knit_graph.connect_loops(parent_loop, child_loop, pull_direction=parent_pull)
-            next_course.append(child_loop)
-        last_course = next_course
+    builder, knit_graph, yarn = co_loops(width)
+    last_course: Sequence[Loop] = knit_graph.get_courses()[0]
+    for _ in range(0, height):
+        assert yarn.last_loop is not None
+        pull_direction = yarn.last_loop.pull_directions[0] if yarn.last_loop.has_parent_loops else Pull_Direction.BtF
+        last_course = [
+            builder.knit(yarn, [parent_loop], pull_direction=pull_direction if i % 2 == 0 else pull_direction.opposite)
+            for i, parent_loop in enumerate(reversed(last_course))
+        ]
     return knit_graph
 
 
-def seed_swatch(width: int, height: int) -> Knit_Graph:
+def seed_swatch(width: int, height: int) -> Knit_Graph[Loop]:
     """Generate a seed stitch swatch with a checkerboard pattern of knit and purl stitches.
 
     This creates a textured fabric where each stitch alternates between knit and purl both horizontally and vertically, creating a bumpy, non-curling fabric texture.
@@ -136,30 +113,19 @@ def seed_swatch(width: int, height: int) -> Knit_Graph:
     Returns:
         Knit_Graph: A knit graph representing a seed stitch swatch with checkerboard knit-purl pattern.
     """
-    knit_graph, yarn = co_loops(width)
-    last_course = knit_graph.get_courses()[0]
-    next_course = []
-    next_pull = Pull_Direction.BtF
-    for parent_loop in reversed(last_course):
-        child_loop = yarn.make_loop_on_end()
-        knit_graph.connect_loops(parent_loop, child_loop, pull_direction=next_pull)
-        next_pull = next_pull.opposite()
-        next_course.append(child_loop)
-    last_course = next_course
-    for _ in range(1, height):
-        next_course = []
-        for parent_loop in reversed(last_course):
-            grand_parent = parent_loop.parent_loops[0]
-            parent_pull = knit_graph.get_pull_direction(grand_parent, parent_loop)
-            assert isinstance(parent_pull, Pull_Direction)
-            child_loop = yarn.make_loop_on_end()
-            knit_graph.connect_loops(parent_loop, child_loop, pull_direction=parent_pull.opposite())
-            next_course.append(child_loop)
-        last_course = next_course
+    builder, knit_graph, yarn = co_loops(width)
+    last_course: Sequence[Loop] = knit_graph.get_courses()[0]
+    for _ in range(0, height):
+        assert yarn.last_loop is not None
+        pull_direction = yarn.last_loop.pull_directions[0] if yarn.last_loop.has_parent_loops else Pull_Direction.BtF
+        last_course = [
+            builder.knit(yarn, [parent_loop], pull_direction=pull_direction.opposite if i % 2 == 0 else pull_direction)
+            for i, parent_loop in enumerate(reversed(last_course))
+        ]
     return knit_graph
 
 
-def lace_mesh(width: int, height: int) -> Knit_Graph:
+def lace_mesh(width: int, height: int) -> Knit_Graph[Loop]:
     """Generate a mesh pattern with alternating left and right leaning decrease paired to yarn-overs.
     These pairings create a basic lace pattern with eyelets formed around the increases.
 
@@ -170,73 +136,31 @@ def lace_mesh(width: int, height: int) -> Knit_Graph:
     Returns:
         Knit_Graph: A knit graph representing a mesh swatch.
     """
-    knit_graph, yarn = co_loops(width)
-    last_course = knit_graph.get_courses()[0]
-    next_course = []
-    for parent_loop in reversed(last_course):
-        child_loop = yarn.make_loop_on_end()
-        knit_graph.connect_loops(parent_loop, child_loop, pull_direction=Pull_Direction.BtF)
-        next_course.append(child_loop)
-    last_course = next_course
+    builder, knit_graph, yarn = co_loops(width)
+    last_course = [builder.knit(yarn, [p]) for p in reversed(knit_graph.get_courses()[0])]
     for _ in range(1, height):
-        # Make the lace course
-        next_course = []
-        yo_parent = None
-        prior_child = None
-        for i, parent_loop in enumerate(reversed(last_course)):
-            child_loop = yarn.make_loop_on_end()
-            if i % 3 == 0:  # Just knit every third stitch
-                knit_graph.connect_loops(
-                    parent_loop,
-                    child_loop,
-                    pull_direction=Pull_Direction.BtF,
-                    stack_position=0,
-                )
-            elif i % 6 == 1:  # Second of every 6 stitches (0 indexed) is yarn over before a decrease.
-                yo_parent = parent_loop
-            elif i % 6 == 2:  # Third of every 6 stitches is bottom of decrease with prior yarn-over's parent
-                knit_graph.connect_loops(
-                    parent_loop,
-                    child_loop,
-                    pull_direction=Pull_Direction.BtF,
-                    stack_position=0,
-                )
-                assert isinstance(yo_parent, Loop)
-                knit_graph.connect_loops(
-                    yo_parent,
-                    child_loop,
-                    pull_direction=Pull_Direction.BtF,
-                    stack_position=1,
-                )
-            elif i % 6 == 4:  # Fifth of every six stitches is bottom of decrease with next yarn-over's parent
-                knit_graph.connect_loops(
-                    parent_loop,
-                    child_loop,
-                    pull_direction=Pull_Direction.BtF,
-                    stack_position=0,
-                )
-                prior_child = child_loop
-            elif i % 6 == 5:  # The last of six stitches is the top of the prior decrease and new yarn-over
-                assert isinstance(prior_child, Loop)
-                knit_graph.connect_loops(
-                    parent_loop,
-                    prior_child,
-                    pull_direction=Pull_Direction.BtF,
-                    stack_position=1,
-                )
-            next_course.append(child_loop)
-        last_course = next_course
-        # Make a basic jersey course
+        dec1 = last_course[1::3]
+        dec2 = last_course[2::3]
+        decs = [
+            dec_parents if i % 2 == 0 else (dec_parents[1], dec_parents[0])
+            for i, dec_parents in enumerate(zip(reversed(dec1), reversed(dec2), strict=False))
+        ]
+        knits = last_course[0::3]
         next_course = []
-        for parent_loop in reversed(last_course):
-            child_loop = yarn.make_loop_on_end()
-            knit_graph.connect_loops(parent_loop, child_loop, pull_direction=Pull_Direction.BtF)
-            next_course.append(child_loop)
-        last_course = next_course
+        for i, parent_loop in enumerate(reversed(knits)):
+            next_course.append(builder.knit(yarn, [parent_loop]))
+            if len(decs) > 0:
+                if i % 2 == 0:
+                    next_course.append(builder.tuck(yarn))
+                    next_course.append(builder.knit(yarn, decs.pop(0)))
+                else:
+                    next_course.append(builder.knit(yarn, decs.pop(0)))
+                    next_course.append(builder.tuck(yarn))
+        last_course = [builder.knit(yarn, [p]) for p in reversed(next_course)]
     return knit_graph
 
 
-def twist_cable(width: int, height: int) -> Knit_Graph:
+def twist_cable(width: int, height: int) -> Knit_Graph[Loop]:
     """Generate a twisted cable pattern with alternating crossing directions and purl separators.
 
     This creates a cable pattern with 1x1 twists that alternate direction every two rows, separated by purl wales to make the cable structure more prominent.
@@ -253,34 +177,31 @@ def twist_cable(width: int, height: int) -> Knit_Graph:
     # p k/k p ->: 1-2
     # p k k p <-: 0-1
     # 0 1 2 3
-    knit_graph, yarn = co_loops(width)
-    last_course = knit_graph.get_courses()[0]
-    next_course = []
+    builder, knit_graph, yarn = co_loops(width)
     pull_directions = [
         Pull_Direction.FtB,
         Pull_Direction.BtF,
         Pull_Direction.BtF,
         Pull_Direction.FtB,
     ]
-    for i, parent_loop in enumerate(reversed(last_course)):
-        child_loop = yarn.make_loop_on_end()
-        knit_graph.connect_loops(parent_loop, child_loop, pull_direction=pull_directions[i % 4])
-        next_course.append(child_loop)
-    last_course = next_course
-    crossing = Crossing_Direction.Over_Right
-    for r in range(1, height):
-        next_course = [yarn.make_loop_on_end() for _ in last_course]
-        for i, parent_loop in enumerate(reversed(last_course)):
-            if r % 2 == 0 or i % 4 == 0 or i % 4 == 3:  # not cable row (even) or in purl wale
-                child_loop = next_course[i]
-            elif i % 4 == 1:
-                child_loop = next_course[i + 1]
+    last_course = [
+        builder.knit(yarn, [p], pull_directions[i % 4]) for i, p in enumerate(reversed(knit_graph.get_courses()[0]))
+    ]
+    for r in range(1, height, 2):
+        crossed_course: list[Loop] = []
+        for i, parent_loop in enumerate(last_course):
+            if i % 4 == 2:
+                crossed_course.insert(-1, parent_loop)
+            else:
+                crossed_course.append(parent_loop)
+        last_course = [builder.knit(yarn, [p]) for p in reversed(crossed_course)]
+        left_cable_loops = last_course[-2:0:-4]
+        right_cable_loops = last_course[-3:0:-4]
+        for left_loop, right_loop in zip(left_cable_loops, right_cable_loops, strict=False):
+            if r % 4 == 1:
+                builder.xfer(left_loop, over_loops_to_right=[right_loop])
             else:
-                child_loop = next_course[i - 1]
-            knit_graph.connect_loops(parent_loop, child_loop, pull_direction=pull_directions[i % 4])
-        if r % 2 == 1:  # cable row
-            for left_loop, right_loop in zip(next_course[1::4], next_course[2::4], strict=False):
-                knit_graph.add_crossing(left_loop, right_loop, crossing)
-            crossing = ~crossing
-        last_course = next_course
+                builder.xfer(left_loop, under_loops_to_right=[right_loop])
+        last_course = [builder.knit(yarn, [p]) for p in reversed(last_course)]
+
     return knit_graph