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

knit_graphs/artin_wale_braids/Loop_Braid_Graph.py

@@ -3,82 +3,81 @@
 This module provides the Loop_Braid_Graph class which tracks crossing relationships between loops in cable knitting patterns using a directed graph structure.
 """
 
-from typing import cast
+from __future__ import annotations
 
-from networkx import DiGraph
+from typing import TypeVar
 
 from knit_graphs.artin_wale_braids.Crossing_Direction import Crossing_Direction
+from knit_graphs.directed_loop_graph import Directed_Loop_Graph
 from knit_graphs.Loop import Loop
 
+LoopT = TypeVar("LoopT", bound=Loop)
 
-class Loop_Braid_Graph:
+
+class Loop_Braid_Graph(Directed_Loop_Graph[LoopT, Crossing_Direction]):
     """A graph structure that tracks crossing braid edges between loops in cable patterns.
 
     This class maintains a directed graph where nodes are loops and edges represent cable crossings between those loops.
     It provides methods to add crossings, query crossing relationships, and determine which loops cross with a given loop.
-
-    Attributes:
-        loop_crossing_graph (DiGraph): A NetworkX directed graph storing loop crossing relationships with crossing direction attributes.
     """
 
-    _CROSSING = "crossing"
-
     def __init__(self) -> None:
         """Initialize an empty loop braid graph with no crossings."""
-        self.loop_crossing_graph: DiGraph = DiGraph()
-
-    def add_crossing(self, left_loop: Loop, right_loop: Loop, crossing_direction: Crossing_Direction) -> None:
-        """Add a crossing edge between two loops with the specified crossing direction.
+        super().__init__()
 
+    def get_crossing(self, left_loop: LoopT, right_loop: LoopT) -> 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.loop_crossing_graph.add_edge(left_loop, right_loop, crossing=crossing_direction)
 
-    def remove_loop(self, loop: Loop) -> None:
-        """
-        Removes any crossings that involve the given loop.
-        Args:
-            loop (Loop): The loop to remove.
+        Returns:
+            Crossing_Direction: The crossing direction between the left and right loop. Defaults to No_Cross if no explicit crossing was previously defined.
         """
-        if loop in self:
-            self.loop_crossing_graph.remove_node(loop)
+        if self.has_edge(left_loop, right_loop):
+            return self.get_edge(left_loop, right_loop)
+        elif self.has_edge(right_loop, left_loop):
+            return self.get_edge(right_loop, left_loop).opposite
+        else:
+            return Crossing_Direction.No_Cross
 
-    def __contains__(self, item: Loop | tuple[Loop, Loop]) -> bool:
-        """Check if a loop or loop pair is contained in the braid graph.
+    def add_crossing(self, left_loop: LoopT, right_loop: LoopT, crossing_direction: Crossing_Direction) -> None:
+        """Add a crossing edge between two loops with the specified crossing direction.
 
-        Args:
-            item (Loop | tuple[Loop, Loop]): Either a single loop to check for node membership, or a tuple of loops to check for edge membership.
+        If the opposite crossing edge has already been defined, it will be removed from the graph so that only one crossing relationship is ever defined for each pair of the loops.
 
-        Returns:
-            bool: True if the loop is a node in the graph (for single loop) or if there is an edge between the loops (for tuple).
+        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.
         """
-        if isinstance(item, Loop):
-            return item in self.loop_crossing_graph.nodes
-        else:
-            return bool(self.loop_crossing_graph.has_edge(item[0], item[1]))
+        if self.has_edge(right_loop, left_loop):  # Remove the edge that will be implied by the new crossing formation.
+            self.remove_edge(right_loop, left_loop)
+        if left_loop not in self:
+            self.add_loop(left_loop)
+        if right_loop not in self:
+            self.add_loop(right_loop)
+        self.add_edge(left_loop, right_loop, crossing_direction)
 
-    def left_crossing_loops(self, left_loop: Loop) -> list[Loop]:
+    def left_crossing_loops(self, left_loop: LoopT) -> set[LoopT]:
         """Get all loops that cross with the given loop when it is on the left side.
 
         Args:
             left_loop (Loop): The loop on the left side of potential crossings.
 
         Returns:
-            list[Loop]: List of loops that this loop crosses over on the right side. Empty list if the loop is not in the graph or has no crossings.
+            set[Loop]: Set of loops that this loop crosses over on the right side. Empty set if the loop is not in the graph or has no crossings.
         """
         if left_loop not in self:
-            return []
+            return set()
         else:
-            return [
+            return {
                 rl
-                for rl in self.loop_crossing_graph.successors(left_loop)
+                for rl in self.successors(left_loop)
                 if self.get_crossing(left_loop, rl) is not Crossing_Direction.No_Cross
-            ]
+            }
 
-    def right_crossing_loops(self, right_loop: Loop) -> list[Loop]:
+    def right_crossing_loops(self, right_loop: LoopT) -> set[LoopT]:
         """Get all loops that cross with the given loop when it is on the right side.
 
         Args:
@@ -88,29 +87,10 @@ class Loop_Braid_Graph:
             list[Loop]: List of loops that cross this loop from the left side. Empty list if the loop is not in the graph or has no crossings.
         """
         if right_loop not in self:
-            return []
+            return set()
         else:
-            return [
+            return {
                 l
-                for l in self.loop_crossing_graph.predecessors(right_loop)
+                for l in self.predecessors(right_loop)
                 if self.get_crossing(l, right_loop) is not Crossing_Direction.No_Cross
-            ]
-
-    def get_crossing(self, left_loop: Loop, right_loop: Loop) -> Crossing_Direction:
-        """Get the crossing direction between two loops, creating a no-cross edge if none exists.
-
-        If no edge exists between the loops, this method automatically adds a no-crossing edge to maintain consistency in the graph structure.
-
-        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.
-
-        Returns:
-            Crossing_Direction: The crossing direction between the left and right loop. Defaults to No_Cross if no explicit crossing was previously defined.
-        """
-        if not self.loop_crossing_graph.has_edge(left_loop, right_loop):
-            self.add_crossing(left_loop, right_loop, Crossing_Direction.No_Cross)
-        return cast(
-            Crossing_Direction,
-            self.loop_crossing_graph[left_loop][right_loop][self._CROSSING],
-        )
+            }

knit_graphs/artin_wale_braids/Wale.py

@@ -5,19 +5,19 @@ This module defines the Wale class which represents a vertical column of stitche
 
 from __future__ import annotations
 
-from collections.abc import Iterator
-from typing import TYPE_CHECKING, cast
-
-from networkx import DiGraph, dfs_preorder_nodes
+from typing import TYPE_CHECKING, TypeVar, overload
 
+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:
+class Wale(Directed_Loop_Graph[LoopT, Pull_Direction]):
     """A data structure representing stitch relationships between loops in a vertical column of a knitted structure.
 
     A wale represents a vertical sequence of loops connected by stitch edges, forming a column in the knitted fabric.
@@ -26,12 +26,9 @@ class Wale:
     Attributes:
         first_loop (Loop | None): The first (bottom) loop in the wale sequence.
         last_loop (Loop | None): The last (top) loop in the wale sequence.
-        stitches (DiGraph): Stores the directed graph of stitch connections within this wale.
     """
 
-    _PULL_DIRECTION: str = "pull_direction"
-
-    def __init__(self, first_loop: Loop, knit_graph: Knit_Graph, end_loop: Loop | None = None) -> None:
+    def __init__(self, first_loop: LoopT, knit_graph: Knit_Graph[LoopT], end_loop: LoopT | None = None) -> None:
         """Initialize a wale optionally starting with a specified loop.
 
         Args:
@@ -41,48 +38,36 @@ class Wale:
                 The loop to terminate the wale with.
                 If no loop is provided or this loop is not found, the wale will terminate at the first loop with no child.
         """
-        self.stitches: DiGraph = DiGraph()
-        self.stitches.add_node(first_loop)
-        self._knit_graph: Knit_Graph = knit_graph
-        self.first_loop: Loop = first_loop
-        self.last_loop: Loop = first_loop
+        super().__init__()
+        self.add_loop(first_loop)
+        self._knit_graph: Knit_Graph[LoopT] = knit_graph
+        self.first_loop: LoopT = first_loop
+        self.last_loop: LoopT = first_loop
         self._build_wale_from_first_loop(end_loop)
 
-    def _build_wale_from_first_loop(self, end_loop: Loop | None) -> None:
-        while self._knit_graph.has_child_loop(self.last_loop):
-            child = self._knit_graph.get_child_loop(self.last_loop)
-            assert isinstance(child, Loop)
-            self.add_loop_to_end(child)
-            if end_loop is not None and child is end_loop:
-                return  # found the end loop, so wrap up the wale
-
-    def add_loop_to_end(self, loop: Loop) -> None:
+    def overlaps(self, other: Wale) -> bool:
         """
-        Add a loop to the end (top) of the wale with the specified pull direction.
-
         Args:
-            loop (Loop): The loop to add to the end of the wale.
+            other (Wale): The other wale to compare against for overlapping loops.
+
+        Returns:
+            bool: True if the other wale has any overlapping loop(s) with this wale, False otherwise.
         """
-        self.stitches.add_edge(
-            self.last_loop,
-            loop,
-            pull_direction=self._knit_graph.get_pull_direction(self.last_loop, loop),
-        )
-        self.last_loop = loop
+        return any(loop in other for loop in self)
 
-    def get_stitch_pull_direction(self, u: Loop, v: Loop) -> Pull_Direction:
+    def get_pull_direction(self, u: LoopT, v: LoopT) -> Pull_Direction:
         """Get the pull direction of the stitch edge between two loops in this wale.
 
         Args:
-            u (Loop): The parent loop in the stitch connection.
-            v (Loop): The child loop in the stitch connection.
+            u (LoopT): The parent loop in the stitch connection.
+            v (LoopT): The child loop in the stitch connection.
 
         Returns:
             Pull_Direction: The pull direction of the stitch between loops u and v.
         """
-        return cast(Pull_Direction, self.stitches.edges[u, v][self._PULL_DIRECTION])
+        return self.get_edge(u, v)
 
-    def split_wale(self, split_loop: Loop) -> tuple[Wale, Wale | None]:
+    def split_wale(self, split_loop: LoopT) -> tuple[Wale[LoopT], Wale[LoopT] | None]:
         """
         Split this wale at the specified loop into two separate wales.
 
@@ -92,19 +77,35 @@ class Wale:
             split_loop (Loop): The loop at which to split the wale. This loop will appear in both resulting wales.
 
         Returns:
-            tuple[Wale, Wale | None]:
+            tuple[Wale[LoopT], Wale[LoopT] | None]:
                 A tuple containing:
                 * The first wale (from start to split_loop). This will be the whole wale if the split_loop is not found.
                 * The second wale (from split_loop to end). This will be None if the split_loop is not found.
         """
         if split_loop in self:
             return (
-                Wale(self.first_loop, self._knit_graph, end_loop=split_loop),
-                Wale(split_loop, self._knit_graph, end_loop=self.last_loop),
+                Wale[LoopT](self.first_loop, self._knit_graph, end_loop=split_loop),
+                Wale[LoopT](split_loop, self._knit_graph, end_loop=self.last_loop),
             )
         else:
             return self, None
 
+    def _build_wale_from_first_loop(self, end_loop: LoopT | None) -> None:
+        for child in [*self._knit_graph.dfs_preorder_loops(self.first_loop)][1:]:
+            self.add_loop_to_end(child)
+            if end_loop is not None and child is end_loop:
+                return  # found the end loop, so wrap up the wale
+
+    def add_loop_to_end(self, loop: LoopT) -> None:
+        """
+        Add a loop to the end (top) of the wale.
+        Args:
+            loop (T): The loop to add to the end of the wale.
+        """
+        self.add_loop(loop)
+        self.add_edge(self.last_loop, loop, self._knit_graph.get_edge(self.last_loop, loop))
+        self.last_loop = loop
+
     def __eq__(self, other: object) -> bool:
         """
         Args:
@@ -117,46 +118,35 @@ class Wale:
             return False
         return not any(l != o for l, o in zip(self, other, strict=False))
 
-    def __len__(self) -> int:
-        """Get the number of loops in this wale.
+    @overload
+    def __getitem__(self, item: int) -> LoopT: ...
 
-        Returns:
-            int: The total number of loops in this wale.
-        """
-        return len(self.stitches.nodes)
-
-    def __iter__(self) -> Iterator[Loop]:
-        """Iterate over loops in this wale from first to last.
+    @overload
+    def __getitem__(self, item: tuple[LoopT | int, LoopT | int]) -> Pull_Direction: ...
 
-        Returns:
-            Iterator[Loop]: An iterator over the loops in this wale in their sequential order from bottom to top.
-        """
-        return cast(Iterator[Loop], dfs_preorder_nodes(self.stitches, source=self.first_loop))
+    @overload
+    def __getitem__(self, item: slice) -> list[LoopT]: ...
 
-    def __getitem__(self, item: int | slice) -> Loop | list[Loop]:
-        """Get loop(s) at the specified index or slice within this wale.
+    def __getitem__(self, item: int | tuple[LoopT | int, LoopT | int] | slice) -> LoopT | Pull_Direction | list[LoopT]:
+        """Get a loop by its ID from this yarn.
 
         Args:
-            item (int | slice): The index of a single loop or a slice for multiple loops.
+            item (int | tuple[LoopT | int, LoopT | int] | slice):
+                The loop ,loop ID, or float between two loops to retrieve from this yarn.
+                If given a slice, it will retrieve the elements between the specified indices in the standard ordering of loops along the wale.
 
         Returns:
-            Loop | list[Loop]: The loop at the specified index, or a list of loops for a slice.
-        """
-        if isinstance(item, int):
-            return cast(Loop, self.stitches.nodes[item])
-        elif isinstance(item, slice):
-            return list(self)[item]
-
-    def __contains__(self, item: Loop) -> bool:
-        """Check if a loop is contained in this wale.
-
-        Args:
-            item (Loop): The loop to check for membership in this wale.
+            LoopT: The loop on the yarn with the matching ID.
+            Stitch_Edge: The edge data for the given pair of loops forming a stitch in the wale.
+            list[LoopT]: The loops in the slice of the wale based on their ordering along the wale.
 
-        Returns:
-            bool: True if the loop is in this wale, False otherwise.
+        Raises:
+            KeyError: If the item is not found on this yarn.
         """
-        return bool(self.stitches.has_node(item))
+        if isinstance(item, slice):
+            return list(self)[item]
+        else:
+            return super().__getitem__(item)
 
     def __hash__(self) -> int:
         """
@@ -180,14 +170,3 @@ class Wale:
             str: The string representation of this wale.
         """
         return str(self)
-
-    def overlaps(self, other: Wale) -> bool:
-        """Check if this wale has any loops in common with another wale.
-
-        Args:
-            other (Wale): The other wale to compare against for overlapping loops.
-
-        Returns:
-            bool: True if the other wale has any overlapping loop(s) with this wale, False otherwise.
-        """
-        return any(loop in other for loop in self)

knit_graphs/artin_wale_braids/Wale_Braid.py

@@ -4,11 +4,16 @@ This module provides the Wale_Braid class which represents complex cable knittin
 using concepts from algebraic topology to model how wales cross over and under each other.
 """
 
+from typing import Generic, TypeVar
+
 from knit_graphs.artin_wale_braids.Wale_Braid_Word import Wale_Braid_Word
 from knit_graphs.artin_wale_braids.Wale_Group import Wale_Group
+from knit_graphs.Loop import Loop
+
+LoopT = TypeVar("LoopT", bound=Loop)
 
 
-class Wale_Braid:
+class Wale_Braid(Generic[LoopT]):
     """A model of knitted structure as a set of crossing wales using Artin braid groups.
 
     This class represents complex cable knitting patterns using mathematical braid theory,
@@ -20,7 +25,7 @@ class Wale_Braid:
         wale_words (list[Wale_Braid_Word]): The sequence of braid words that describe the crossing operations between wales.
     """
 
-    def __init__(self, wale_groups: list[Wale_Group], wale_words: list[Wale_Braid_Word]) -> None:
+    def __init__(self, wale_groups: list[Wale_Group], wale_words: list[Wale_Braid_Word[LoopT]]) -> None:
         """Initialize a wale braid with the specified groups and braid words.
 
         Args:

knit_graphs/artin_wale_braids/Wale_Braid_Word.py

@@ -5,33 +5,40 @@ This module provides the Wale_Braid_Word class which represents a single step in
 
 from __future__ import annotations
 
+from collections.abc import Iterator
+from typing import Generic, TypeVar
+
 from knit_graphs.artin_wale_braids.Crossing_Direction import Crossing_Direction
 from knit_graphs.Loop import Loop
 
+LoopT = TypeVar("LoopT", bound=Loop)
+
 
-class Wale_Braid_Word:
+class Wale_Braid_Word(Generic[LoopT]):
     """A representation of loop crossings over a set of loops in a common course.
 
     This class represents a single braid word in the mathematical sense, describing how a set of loops cross over or under each other within a horizontal course.
     Each braid word can be inverted and applied to determine the new ordering of loops after the crossing operations.
 
     Attributes:
-        loops (list[Loop]): The ordered list of loops that participate in this braid word.
+        loops (list[LoopT]): The ordered list of loops that participate in this braid word.
         crossings (dict[int, Crossing_Direction]): A mapping from loop indices to their crossing directions, where each key represents the index of a loop that crosses with the loop at index+1.
     """
 
-    def __init__(self, loops: list[Loop], crossings: dict[int, Crossing_Direction]) -> None:
+    def __init__(self, loops: list[LoopT], crossings: dict[int, Crossing_Direction]) -> None:
         """Initialize a wale braid word with the specified loops and crossing operations.
 
         Args:
-            loops (list[Loop]): The ordered list of loops that participate in this braid word.
-            crossings (dict[int, Crossing_Direction]): A dictionary mapping loop indices to crossing directions.
-            Each index-key indicates that the loop at  that index crosses with the loop at index+1 in the specified direction.
+            loops (list[LoopT]): The ordered list of loops that participate in this braid word.
+            crossings (dict[int, Crossing_Direction]):
+                A dictionary mapping loop indices to crossing directions.
+                Each index-key indicates that the loop at that index crosses with the loop at index+1 in the specified direction.
         """
-        self.loops: list[Loop] = loops
+        self.loops: list[LoopT] = loops
         self.crossings: dict[int, Crossing_Direction] = crossings
 
-    def new_loop_order(self) -> list[Loop]:
+    @property
+    def new_loop_order(self) -> list[LoopT]:
         """Calculate the new ordering of loops after applying all crossing operations.
 
         This method applies all the crossing operations defined in this braid word to determine the final ordering of loops.
@@ -40,7 +47,7 @@ class Wale_Braid_Word:
         Returns:
             list[Loop]: The list of loops in their new order after all crossing operations have been applied.
         """
-        new_loops: list[Loop] = [*self.loops]
+        new_loops = [*self]
         for i in sorted(self.crossings.keys(), reverse=True):
             moves_left = new_loops[i + 1]
             new_loops[i + 1] = new_loops[i]
@@ -48,17 +55,28 @@ class Wale_Braid_Word:
 
         return new_loops
 
-    def __invert__(self) -> Wale_Braid_Word:
+    def is_inversion(self, other: Wale_Braid_Word) -> bool:
+        """Check if another braid word is the inverse of this braid word.
+
+        Args:
+            other (Wale_Braid_Word): The other braid word to compare against for inversion relationship.
+
+        Returns:
+            bool: True if the other braid word is equal to the inverse of this braid word, False otherwise.
+        """
+        invert = ~self
+        return other == invert
+
+    def __invert__(self) -> Wale_Braid_Word[LoopT]:
         """Create the inverse braid word that undoes the operations of this braid word.
 
         The inverse braid word uses the new loop order as its starting configuration and inverts all crossing directions to reverse the effect of the original braid word.
 
         Returns:
-            Wale_Braid_Word: A new braid word that represents the inverse operation of this braid word.
+            Wale_Braid_Word[LoopT]: A new braid word that represents the inverse operation of this braid word.
         """
-        new_loops = self.new_loop_order()
         new_crossings = {i: ~c for i, c in self.crossings.items()}
-        return Wale_Braid_Word(new_loops, new_crossings)
+        return Wale_Braid_Word[LoopT](self.new_loop_order, new_crossings)
 
     def __eq__(self, other: object) -> bool:
         """Check equality with another wale braid word.
@@ -79,17 +97,12 @@ class Wale_Braid_Word:
             and all(other.crossings[i] == cd for i, cd in self.crossings.items())
         )
 
-    def is_inversion(self, other: Wale_Braid_Word) -> bool:
-        """Check if another braid word is the inverse of this braid word.
-
-        Args:
-            other (Wale_Braid_Word): The other braid word to compare against for inversion relationship.
-
+    def __iter__(self) -> Iterator[LoopT]:
+        """
         Returns:
-            bool: True if the other braid word is equal to the inverse of this braid word, False otherwise.
+            Iterator[LoopT]: Iteration over the loops in the braid word.
         """
-        invert = ~self
-        return other == invert
+        return iter(self.loops)
 
     def __len__(self) -> int:
         """Get the number of loops in this braid word.