knit-graphs 0.0.5__py3-none-any.whl → 0.0.7__py3-none-any.whl

knit_graphs/__init__.py

@@ -1,3 +1,3 @@
-# SPDX-FileCopyrightText: 2024-present m.hofmann <m.hofmann@northeastern.edu>
-#
-# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2024-present m.hofmann <m.hofmann@northeastern.edu>
+#
+# SPDX-License-Identifier: MIT

knit_graphs/_base_classes.py

@@ -0,0 +1,173 @@
+"""Private module containing base classes for Loops and Yarns. Used to resolve circular dependencies."""
+from __future__ import annotations
+
+from networkx import DiGraph
+
+
+class _Base_Loop:
+    """Base class for Loop objects providing common functionality and interface.
+
+    This class serves as a foundation for Loop implementations and helps resolve circular dependencies between modules. It provides basic loop identification and comparison functionality.
+    """
+
+    def __init__(self, loop_id: int):
+        """Initialize a base loop with the given identifier.
+
+        Args:
+            loop_id (int): The unique identifier for this loop. Must be non-negative.
+        """
+        assert loop_id >= 0, f"{loop_id}: Loop_id must be non-negative"
+        self._loop_id: int = loop_id
+
+    @property
+    def loop_id(self) -> int:
+        """Get the unique identifier of this loop.
+
+        Returns:
+            int: The id of the loop.
+        """
+        return self._loop_id
+
+    def __hash__(self) -> int:
+        """Return hash value based on loop_id for use in sets and dictionaries.
+
+        Returns:
+            int: Hash value of the loop_id.
+        """
+        return self.loop_id
+
+    def __int__(self) -> int:
+        """Convert loop to integer representation using loop_id.
+
+        Returns:
+            int: The loop_id as an integer.
+        """
+        return self.loop_id
+
+    def __eq__(self, other: _Base_Loop) -> bool:
+        """Check equality with another base loop based on loop_id and type.
+
+        Args:
+            other (_Base_Loop): The other loop to compare with.
+
+        Returns:
+            bool: True if both loops have the same class and loop_id, False otherwise.
+        """
+        return isinstance(other, other.__class__) and self.loop_id == other.loop_id
+
+    def __lt__(self, other: _Base_Loop | int) -> bool:
+        """Compare loop_id with another loop or integer for ordering.
+
+        Args:
+            other (_Base_Loop | int): The other loop or integer to compare with.
+
+        Returns:
+            bool: True if this loop's id is less than the other's id.
+        """
+        return int(self.loop_id) < int(other)
+
+    def __repr__(self) -> str:
+        """Return string representation of the loop.
+
+        Returns:
+            str: String representation showing "Loop {loop_id}".
+        """
+        return f"Loop {self.loop_id}"
+
+
+class _Base_Yarn:
+    """Base class for Yarn objects providing common functionality and interface.
+
+    This class serves as a foundation for Yarn implementations and helps resolve circular dependencies between modules. It maintains a directed graph structure for managing loop relationships.
+    """
+
+    def __init__(self) -> None:
+        """Initialize a base yarn with an empty directed graph for loop relationships."""
+        self.loop_graph: DiGraph = DiGraph()
+
+    def prior_loop(self, loop: _Base_Loop) -> _Base_Loop | None:
+        """Find the loop that precedes the given loop on this yarn.
+
+        Args:
+            loop (_Base_Loop): The loop to find the preceding loop of.
+
+        Returns:
+            _Base_Loop | None: The loop that precedes the given loop on the yarn, or None if there is no prior loop.
+
+        Raises:
+            NotImplementedError: This is an abstract base class which must be extended with the correct implementation.
+        """
+        raise NotImplementedError("Implemented by base class")
+
+    def next_loop(self, loop: _Base_Loop) -> _Base_Loop | None:
+        """Find the loop that follows the given loop on this yarn.
+
+        Args:
+            loop (_Base_Loop): The loop to find the next loop of.
+
+        Returns:
+            _Base_Loop | None: The loop that follows the given loop on the yarn, or None if there is no next loop.
+
+        Raises:
+            NotImplementedError: This is an abstract base class which must be extended with the correct implementation.
+        """
+        raise NotImplementedError("Implemented by base class")
+
+
+class _Base_Wale:
+    """Base class for Wale objects providing common functionality and interface.
+
+    This class serves as a foundation for Wale implementations and maintains a directed graph structure for managing stitch relationships within a wale (vertical column of stitches).
+    """
+
+    def __init__(self) -> None:
+        """Initialize a base wale with an empty directed graph for stitch relationships."""
+        self.stitches: DiGraph = DiGraph()
+
+
+class _Base_Knit_Graph:
+    """Base class for Knit Graph objects providing common functionality and interface.
+
+    This class serves as a foundation for Knit Graph implementations and maintains a directed graph structure for managing stitch relationships throughout the entire knitted structure.
+    """
+
+    def __init__(self) -> None:
+        """Initialize a base knit graph with an empty directed graph for stitch relationships."""
+        self.stitch_graph: DiGraph = DiGraph()
+
+    @property
+    def last_loop(self) -> None | _Base_Loop:
+        """Get the most recently added loop in the graph.
+
+        Returns:
+            None | _Base_Loop: The last loop added to the graph, or None if the graph contains no loops.
+
+        Raises:
+            NotImplementedError: This is an abstract base class which must be extended with the correct implementation.
+        """
+        raise NotImplementedError("Implemented by base class")
+
+    def add_loop(self, loop: _Base_Loop) -> None:
+        """Add a loop to the knit graph structure.
+
+        Args:
+            loop (_Base_Loop): The loop to add to the graph.
+
+        Raises:
+            NotImplementedError: This is an abstract base class which must be extended with the correct implementation.
+        """
+        raise NotImplementedError("Implemented by base class")
+
+    def get_wales_ending_with_loop(self, last_loop: _Base_Loop) -> list[_Base_Wale]:
+        """Get all wales (vertical columns) that terminate at the specified loop.
+
+        Args:
+            last_loop (_Base_Loop): The loop terminating the list of wales to be returned.
+
+        Returns:
+            list[_Base_Wale]: The list of wales that end at the given loop. This will only be multiple wales if the loop is a child of a decrease stitch.
+
+        Raises:
+            NotImplementedError: This is an abstract base class which must be extended with the correct implementation.
+        """
+        raise NotImplementedError

knit_graphs/artin_wale_braids/Crossing_Direction.py

@@ -1,15 +1,74 @@
-"""Module containing the Crossing_Direction Enum"""
-from enum import Enum
-
-
-class Crossing_Direction(Enum):
-    """Enumeration of crossing values between loops"""
-    Over_Right = "+"
-    Under_Right = "-"
-    No_Cross = "|"
-
-    def __invert__(self):
-        if self is Crossing_Direction.Over_Right:
-            return Crossing_Direction.Under_Right
-        else:
-            return Crossing_Direction.Over_Right
+"""Module containing the Crossing_Direction Enum.
+
+This module defines the Crossing_Direction enumeration which represents the different ways loops can cross over or under each other in cable knitting patterns.
+"""
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Crossing_Direction(Enum):
+    """Enumeration of crossing directions between loops in cable knitting patterns.
+
+    This enumeration represents the three possible crossing relationships between loops: crossing over to the right, crossing under to the right, or no crossing at all.
+    These directions are fundamental to representing cable structures in knitted fabrics.
+    """
+    Over_Right = "+"
+    Under_Right = "-"
+    No_Cross = "|"
+
+    @property
+    def opposite(self) -> Crossing_Direction:
+        """Get the opposite crossing direction of this direction.
+
+        The Over_Right and Under_Right crossing directions are opposites of each other, while No_Cross is its own opposite since there is no crossing to invert.
+
+        Returns:
+            Crossing_Direction: The opposite of this crossing direction. Over_Right returns Under_Right, Under_Right returns Over_Right, and No_Cross returns No_Cross.
+        """
+        if self is Crossing_Direction.Over_Right:
+            return Crossing_Direction.Under_Right
+        elif self is Crossing_Direction.Under_Right:
+            return Crossing_Direction.Over_Right
+        else:
+            return Crossing_Direction.No_Cross
+
+    def __invert__(self) -> Crossing_Direction:
+        """Get the opposite crossing direction using the bitwise inversion operator.
+
+        Returns:
+            Crossing_Direction: The opposite crossing direction, same as calling the opposite property.
+        """
+        return self.opposite
+
+    def __neg__(self) -> Crossing_Direction:
+        """Get the opposite crossing direction using the negation operator.
+
+        Returns:
+            Crossing_Direction: The opposite crossing direction, same as calling the opposite property.
+        """
+        return self.opposite
+
+    def __str__(self) -> str:
+        """Get the string representation of the crossing direction.
+
+        Returns:
+            str: The symbol representing the crossing direction ("+", "-", or "|").
+        """
+        return str(self.value)
+
+    def __repr__(self) -> str:
+        """Get the representation string of the crossing direction for debugging.
+
+        Returns:
+            str: The name of the crossing direction ("Over_Right", "Under_Right", or "No_Cross").
+        """
+        return str(self.name)
+
+    def __hash__(self) -> int:
+        """Get the hash value of the crossing direction for use in sets and dictionaries.
+
+        Returns:
+            int: Hash value based on the crossing direction value.
+        """
+        return hash(self.value)

knit_graphs/artin_wale_braids/Loop_Braid_Graph.py

@@ -1,62 +1,95 @@
-"""Module containing the Loop Braid Graph class."""
-import networkx
-
-from knit_graphs.Loop import Loop
-from knit_graphs.artin_wale_braids.Crossing_Direction import Crossing_Direction
-
-
-class Loop_Braid_Graph:
-    """
-        Tracks crossing braid edges between loops
-    """
-
-    def __init__(self):
-        self.loop_crossing_graph: networkx.DiGraph = networkx.DiGraph()
-
-    def add_crossing(self, left_loop: Loop, right_loop: Loop, crossing_direction: Crossing_Direction):
-        """
-        Adds edge between loops with attribute of the crossing direction.
-        :param left_loop: Loop on the left side of the crossing.
-        :param right_loop: Loop on the right side of the crossing.
-        :param crossing_direction: The crossing direction is (over, under, none) between loops.
-        """
-        self.loop_crossing_graph.add_edge(left_loop, right_loop, crossing=crossing_direction)
-
-    def __contains__(self, item: Loop | tuple[Loop, Loop]):
-        if isinstance(item, Loop):
-            return item in self.loop_crossing_graph.nodes
-        else:
-            return self.loop_crossing_graph.has_edge(item[0], item[1])
-
-    def left_crossing_loops(self, left_loop: Loop) -> list[Loop]:
-        """
-        :param left_loop: loop to left side of crossing
-        :return: list of loops this crosses over on right side
-        """
-        if left_loop not in self:
-            return []
-        else:
-            return [rl for rl in self.loop_crossing_graph.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]:
-        """
-        :param right_loop: The loop to find crossings with.
-        :return: The list of loops that leftward cross the right loop.
-        """
-        if right_loop not in self:
-            return []
-        else:
-            return [l for l in self.loop_crossing_graph.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:
-        """
-        Adds no-cross edge if no edge exists between loops
-        :param left_loop: Loop on the left side of the crossing.
-        :param right_loop: Loop on the right side of the crossing.
-        :return: The crossing direction between left and right loop. Defaults to no crossing.
-        """
-        if not self.loop_crossing_graph.has_edge(left_loop, right_loop):
-            self.add_crossing(left_loop, right_loop, Crossing_Direction.No_Cross)
-        return self.loop_crossing_graph[left_loop][right_loop]['crossing']
+"""Module containing the Loop Braid Graph class.
+
+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 networkx import DiGraph
+
+from knit_graphs.artin_wale_braids.Crossing_Direction import Crossing_Direction
+from knit_graphs.Loop import Loop
+
+
+class Loop_Braid_Graph:
+    """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.
+    """
+
+    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.
+
+        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 __contains__(self, item: Loop | tuple[Loop, Loop]) -> bool:
+        """Check if a loop or loop pair is contained in the braid graph.
+
+        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.
+
+        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).
+        """
+        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]))
+
+    def left_crossing_loops(self, left_loop: Loop) -> list[Loop]:
+        """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.
+        """
+        if left_loop not in self:
+            return []
+        else:
+            return [rl for rl in self.loop_crossing_graph.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]:
+        """Get all loops that cross with the given loop when it is on the right side.
+
+        Args:
+            right_loop (Loop): The loop on the right side of potential crossings.
+
+        Returns:
+            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 []
+        else:
+            return [l for l in self.loop_crossing_graph.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]['crossing'])