knit-graphs 0.0.11__tar.gz → 0.0.12__tar.gz

{knit_graphs-0.0.11 → knit_graphs-0.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: knit-graphs
-Version: 0.0.11
+Version: 0.0.12
 Summary: A graph representation of knitted structures where each loop is a node and edges represent yarn and stitch relationships.
 Home-page: https://mhofmann-khoury.github.io/knit_graph/
 License: MIT

{knit_graphs-0.0.11 → knit_graphs-0.0.12}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "poetry.core.masonry.api"  # Use Poetry's build system
 # All the information about your project that will appear on PyPI
 [tool.poetry]
 name = "knit-graphs"
-version = "0.0.11"
+version = "0.0.12"
 description = "A graph representation of knitted structures where each loop is a node and edges represent yarn and stitch relationships."
 authors = ["Megan Hofmann <m.hofmann@northeastern.edu>"]
 maintainers = ["Megan Hofmann <m.hofmann@northeastern.edu>"]

{knit_graphs-0.0.11 → knit_graphs-0.0.12}/src/knit_graphs/Course.py

@@ -5,34 +5,45 @@ This module contains the Course class which represents a horizontal row of loops
 
 from __future__ import annotations
 
-from collections.abc import Iterator
-from typing import TYPE_CHECKING, cast
+from collections.abc import Iterator, Sequence
+from typing import TYPE_CHECKING, Generic, TypeVar, overload
 
 from knit_graphs.Loop import Loop
 
 if TYPE_CHECKING:
     from knit_graphs.Knit_Graph import Knit_Graph
 
+LoopT = TypeVar("LoopT", bound=Loop)
 
-class Course:
+
+class Course(Sequence[LoopT], Generic[LoopT]):
     """Course object for organizing loops into knitting rows.
 
     A Course represents a horizontal row of loops in a knitting pattern.
     It maintains an ordered list of loops and provides methods for analyzing the structure and relationships between courses in the knitted fabric.
     """
 
-    def __init__(self, knit_graph: Knit_Graph) -> None:
+    def __init__(self, course_number: int, knit_graph: Knit_Graph[LoopT]) -> None:
         """Initialize an empty course associated with a knit graph.
 
         Args:
             knit_graph (Knit_Graph): The knit graph that this course belongs to.
         """
-        self._knit_graph: Knit_Graph = knit_graph
-        self._loops_in_order: list[Loop] = []
-        self._loop_set: set[Loop] = set()
+        self._course_number: int = course_number
+        self._knit_graph: Knit_Graph[LoopT] = knit_graph
+        self._loops_in_order: list[LoopT] = []
+        self._loop_set: set[LoopT] = set()
 
     @property
-    def loops_in_order(self) -> list[Loop]:
+    def course_number(self) -> int:
+        """
+        Returns:
+            int: The course number of the course.
+        """
+        return self._course_number
+
+    @property
+    def loops_in_order(self) -> list[LoopT]:
         """
         Returns:
             list[Loop]: The list of loops in this course.
@@ -40,22 +51,34 @@ class Course:
         return self._loops_in_order
 
     @property
-    def knit_graph(self) -> Knit_Graph:
+    def loop_ids_in_course(self) -> list[int]:
+        """
+        Returns:
+            list[int]: The loop ids in the course in the order the occur in the course.
+        """
+        return [l.loop_id for l in self.loops_in_order]
+
+    @property
+    def knit_graph(self) -> Knit_Graph[LoopT]:
         """
         Returns:
             Knit_Graph: The knit graph that this course belongs to.
         """
         return self._knit_graph
 
-    def add_loop(self, loop: Loop, index: int | None = None) -> None:
+    def add_loop(self, loop: LoopT, index: int | None = None) -> None:
         """Add a loop to the course at the specified index or at the end.
 
         Args:
             loop (Loop): The loop to add to this course.
             index (int | None, optional): The index position to insert the loop at. If None, appends to the end.
+
+        Raises:
+            ValueError: If the loop is a parent to any loops already in the course.
         """
         for parent_loop in loop.parent_loops:
-            assert parent_loop not in self, f"{loop} has parent {parent_loop}, cannot be added to same course"
+            if parent_loop in self:
+                raise ValueError(f"{loop} has parent {parent_loop}, cannot be added to same course")
         self._loop_set.add(loop)
         if index is None:
             self.loops_in_order.append(loop)
@@ -68,7 +91,7 @@ class Course:
         Returns:
             bool: True if the course has at least one yarn over (loop with no parent loops) to start new wales.
         """
-        return any(not loop.has_parent_loops() for loop in self)
+        return any(not loop.has_parent_loops for loop in self)
 
     def has_decrease(self) -> bool:
         """Check if this course contains any decrease stitches that merge wales.
@@ -78,18 +101,7 @@ class Course:
         """
         return any(len(loop.parent_loops) > 1 for loop in self)
 
-    def __getitem__(self, index: int | slice) -> Loop | list[Loop]:
-        """Get loop(s) at the specified index or slice.
-
-        Args:
-            index (int | slice): The index or slice to retrieve from the course.
-
-        Returns:
-            Loop | list[Loop]: The loop at the specified index, or list of loops for a slice.
-        """
-        return self.loops_in_order[index]
-
-    def in_round_with(self, next_course: Course) -> bool:
+    def in_round_with(self, next_course: Course[LoopT]) -> bool:
         """Check if the next course connects to this course in a circular pattern.
 
         This method determines if the courses are connected in the round (circular knitting) by checking if the next course starts at the beginning of this course.
@@ -100,14 +112,14 @@ class Course:
         Returns:
             bool: True if the next course starts at the beginning of this course, indicating circular knitting.
         """
-        next_start: Loop = cast(Loop, next_course[0])
+        next_start = next_course[0]
         i = 1
-        while not next_start.has_parent_loops():
-            next_start = cast(Loop, next_course[i])
+        while not next_start.has_parent_loops:
+            next_start = next_course[i]
             i += 1
         return self[0] in next_start.parent_loops
 
-    def in_row_with(self, next_course: Course) -> bool:
+    def in_row_with(self, next_course: Course[LoopT]) -> bool:
         """Check if the next course connects to this course in a flat/row pattern.
 
         This method determines if the courses are connected in flat knitting (back and forth) by checking if the next course starts at the end of this course.
@@ -118,39 +130,48 @@ class Course:
         Returns:
             bool: True if the next course starts at the end of this course, indicating flat/row knitting.
         """
-        next_start: Loop = cast(Loop, next_course[0])
+        next_start: LoopT = next_course[0]
         i = 1
-        while not next_start.has_parent_loops():
-            next_start = cast(Loop, next_course[i])
+        while not next_start.has_parent_loops:
+            next_start = next_course[i]
             i += 1
         return self[-1] in next_start.parent_loops
 
-    def __contains__(self, loop: Loop) -> bool:
+    def __contains__(self, loop: object) -> bool:
         """Check if a loop is contained in this course.
 
         Args:
-            loop (Loop): The loop to check for membership in this course.
+            loop (LoopT): The loop to check for membership in this course.
 
         Returns:
             bool: True if the loop is in this course, False otherwise.
         """
         return loop in self._loop_set
 
-    def __iter__(self) -> Iterator[Loop]:
-        """Iterate over loops in this course in order.
+    @overload
+    def __getitem__(self, index: int) -> LoopT: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> list[LoopT]: ...
+
+    def __getitem__(self, index: int | slice) -> LoopT | list[LoopT]:
+        """Get loop(s) at the specified index or slice.
+
+        Args:
+            index (int | slice): The index or slice to retrieve from the course.
 
         Returns:
-            Iterator[Loop]: An iterator over the loops in this course in their natural order.
+            Loop | list[Loop]: The loop at the specified index, or list of loops for a slice.
         """
-        return iter(self.loops_in_order)
+        return self.loops_in_order[index]
 
-    def __reversed__(self) -> Iterator[Loop]:
-        """Iterate over loops in this course in reverse order.
+    def __iter__(self) -> Iterator[LoopT]:
+        """Iterate over loops in this course in order.
 
         Returns:
-            Iterator[Loop]: An iterator over the loops in this course in reverse order.
+            Iterator[Loop]: An iterator over the loops in this course in their natural order.
         """
-        return reversed(self.loops_in_order)
+        return iter(self.loops_in_order)
 
     def __len__(self) -> int:
         """Get the number of loops in this course.
@@ -166,7 +187,7 @@ class Course:
         Returns:
             str: String representation showing the ordered list of loops.
         """
-        return str(self.loops_in_order)
+        return f"Course {self.course_number}: {self.loops_in_order}"
 
     def __repr__(self) -> str:
         """Get string representation of this course for debugging.

knit_graphs-0.0.12/src/knit_graphs/Knit_Graph.py

@@ -0,0 +1,209 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TypeVar
+
+from knit_graphs.artin_wale_braids.Crossing_Direction import Crossing_Direction
+from knit_graphs.artin_wale_braids.Loop_Braid_Graph import Loop_Braid_Graph
+from knit_graphs.artin_wale_braids.Wale import Wale
+from knit_graphs.artin_wale_braids.Wale_Group import Wale_Group
+from knit_graphs.Course import Course
+from knit_graphs.directed_loop_graph import Directed_Loop_Graph
+from knit_graphs.Loop import Loop
+from knit_graphs.Pull_Direction import Pull_Direction
+from knit_graphs.Yarn import Yarn
+
+LoopT = TypeVar("LoopT", bound=Loop)
+
+
+class Knit_Graph(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.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty knit graph with no loops or yarns."""
+        super().__init__()
+        self.braid_graph: Loop_Braid_Graph[LoopT] = Loop_Braid_Graph()
+        self._last_loop: LoopT | None = None
+        self.yarns: set[Yarn[LoopT]] = set()
+
+    @property
+    def last_loop(self) -> LoopT | None:
+        """Get the most recently added loop in the graph.
+
+        Returns:
+            Loop | None: The last loop added to the graph, or None if no loops have been added.
+        """
+        return self._last_loop
+
+    @property
+    def stitch_iter(self) -> Iterator[tuple[LoopT, LoopT, Pull_Direction]]:
+        """
+        Returns:
+            Iterator[tuple[LoopT, LoopT, Pull_Direction]]: Iterator over the edges and edge-data in the graph.
+
+        Notes:
+            No guarantees about the order of the edges.
+        """
+        return self.edge_iter
+
+    def get_pull_direction(self, parent: LoopT | int, child: LoopT | int) -> Pull_Direction:
+        """Get the pull direction of the stitch edge between parent and child loops.
+
+        Args:
+            parent (Loop | int): The parent loop of the stitch edge.
+            child (Loop | int): The child loop of the stitch edge.
+
+        Returns:
+            Pull_Direction: The pull direction of the stitch-edge between the parent and child.
+        """
+        return self.get_edge(parent, child)
+
+    def add_crossing(self, left_loop: LoopT, right_loop: LoopT, crossing_direction: Crossing_Direction) -> None:
+        """Add a cable crossing between two loops with the specified crossing direction.
+
+        Args:
+            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.
+        """
+        self.braid_graph.add_crossing(left_loop, right_loop, crossing_direction)
+
+    def add_loop(self, loop: LoopT) -> None:
+        """Add a loop to the knit graph as a node.
+
+        Args:
+            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.
+        """
+        super().add_loop(loop)
+        if loop.yarn not in self.yarns:
+            self.add_yarn(loop.yarn)
+        if self._last_loop is None or loop > self._last_loop:
+            self._last_loop = loop
+
+    def remove_loop(self, loop: LoopT | int) -> None:
+        """
+        Remove the given loop from the knit graph.
+        Args:
+            loop (Loop | int): The loop or loop_id to be removed.
+
+        Raises:
+            KeyError: If the loop is not in the knit graph.
+
+        """
+        if isinstance(loop, int):
+            loop = self.get_loop(loop)
+        if loop in self.braid_graph:
+            self.braid_graph.remove_loop(loop)  # remove any crossing associated with this loop.
+        # Remove any stitch edges involving this loop.
+        if self.has_child_loop(loop):
+            child_loop = self.get_child_loop(loop)
+            if child_loop is not None:
+                child_loop.remove_parent(loop)
+        super().remove_loop(loop)
+        # Remove loop from any floating positions
+        for yarn in self.yarns:
+            yarn.remove_loop_relative_to_floats(loop)
+        # Remove loop from yarn
+        yarn = loop.yarn
+        yarn.remove_loop(loop)
+        if len(yarn) == 0:  # This was the only loop on that yarn
+            self.yarns.discard(yarn)
+        # Reset last loop
+        if loop is self.last_loop:
+            if len(self.yarns) == 0:  # No loops left
+                self._last_loop = None
+            else:  # Set to the newest loop formed at the end of any yarns.
+                self._last_loop = max(y.last_loop for y in self.yarns if y.last_loop is not None)
+
+    def add_yarn(self, yarn: Yarn[LoopT]) -> None:
+        """Add a yarn to the graph without adding its loops.
+
+        Args:
+            yarn (Yarn[LoopT]): The yarn to be added to the graph structure. This method assumes that loops do not need to be added separately.
+        """
+        self.yarns.add(yarn)
+
+    def connect_loops(
+        self,
+        parent_loop: LoopT,
+        child_loop: LoopT,
+        pull_direction: Pull_Direction = Pull_Direction.BtF,
+        stack_position: int | None = None,
+    ) -> None:
+        """Create a stitch edge by connecting a parent and child loop.
+
+        Args:
+            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.
+        """
+        super().add_edge(parent_loop, child_loop, pull_direction)
+        child_loop.add_parent_loop(parent_loop, stack_position)
+
+    def get_wales_ending_with_loop(self, last_loop: LoopT) -> set[Wale[LoopT]]:
+        """Get all wales (vertical columns of stitches) that end at the specified loop.
+
+        Args:
+            last_loop (Loop): The last loop of the joined set of wales.
+
+        Returns:
+            set[Wale[LoopT]]: The set of wales that end at this loop.
+        """
+        if len(last_loop.parent_loops) == 0:
+            return {Wale[LoopT](last_loop, self)}
+        sources = self.source_loops(last_loop)
+        return {Wale[LoopT](source, self) for source in sources}
+
+    def get_terminal_wales(self) -> dict[LoopT, list[Wale]]:
+        """
+        Get wale groups organized by their terminal loops.
+
+        Returns:
+            dict[Loop, list[Wale]]: Dictionary mapping terminal loops to list of wales that terminate that wale.
+        """
+        wale_groups = {}
+        for loop in self.terminal_loops:
+            wale_groups[loop] = list(self.get_wales_ending_with_loop(loop))
+        return wale_groups
+
+    def get_courses(self) -> list[Course[LoopT]]:
+        """Get all courses (horizontal rows) in the knit graph in chronological order.
+
+        Returns:
+            list[Course[LoopT]: A list of courses representing horizontal rows of loops.
+            The first course contains the initial set of loops. A course change occurs when a loop has a parent loop in the previous course.
+        """
+        courses = []
+        course = Course(0, self)
+        for loop in self.sorted_loops:
+            for parent in loop.parent_loops:
+                if parent in course:  # start a new course
+                    courses.append(course)
+                    course = Course(course.course_number + 1, self)
+                    break
+            course.add_loop(loop)
+        courses.append(course)
+        return courses
+
+    def get_wale_groups(self) -> set[Wale_Group]:
+        """Get wale groups organized by their terminal loops.
+
+        Returns:
+            set[Wale_Group]: 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 {Wale_Group(terminal_loop, self) for terminal_loop in self.terminal_loops}