knit-graphs 0.0.9__tar.gz → 0.0.10__tar.gz

{knit_graphs-0.0.9 → knit_graphs-0.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: knit-graphs
-Version: 0.0.9
+Version: 0.0.10
 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.9 → knit_graphs-0.0.10}/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.9"
+version = "0.0.10"
 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>"]
@@ -52,8 +52,6 @@ include = [
     "README.md",                    # Project description
     "LICENSE",                      # License file
     "docs/**/*",                    # All documentation files
-    # "src/**/data/**/*",           # Example: include data files
-    # "src/**/templates/**/*",      # Example: include template files
 ]
 
 # Exclude files from the distribution package (keeps package size down)
@@ -80,29 +78,11 @@ exclude = [
 python = ">=3.11,<3.14"
 networkx = ">=3.5"
 plotly = "^6.3.0"
-# Examples:
-# requests = "^2.31.0"              # For HTTP requests
-# pydantic = "^2.0.0"               # For data validation
-# click = "^8.1.0"                  # For CLI applications
-# numpy = "^1.24.0"                 # For numerical computing
-# pandas = "^2.0.0"                 # For data manipulation
-
-# =============================================================================
-# OPTIONAL DEPENDENCIES (EXTRAS)
-# =============================================================================
-# Optional dependency groups that users can install with pip install "package[extra]"
-#[tool.poetry.extras]
-# Examples:
-# cli = ["click", "rich"]           # For command-line interface features
-# viz = ["matplotlib", "plotly"]    # For visualization features
-# dev = ["pytest", "mypy"]          # For development tools (though prefer dev dependencies)
 
 # =============================================================================
 # DEVELOPMENT DEPENDENCIES
 # =============================================================================
 # These packages are only needed during development and testing
-
-
 [tool.poetry.group.dev.dependencies]
 importlib-resources = ">=6.5.2"
 
@@ -143,34 +123,6 @@ tox = "^4.11.0"                    # Test across multiple Python versions locall
 # -------------------------------------------------------------------------
 build = "^0.10.0"                  # PEP 517 build tool (for creating distributions)
 
-# =============================================================================
-# DOCUMENTATION-SPECIFIC DEPENDENCIES
-# =============================================================================
-# Separate dependency group for building documentation (allows selective installation)
-[tool.poetry.group.docs.dependencies]
-sphinx = "^7.1.0"                    # Documentation generator (main tool)
-sphinx-rtd-theme = "^1.3.0"         # Professional-looking theme
-sphinx-autodoc-typehints = "^1.24.0" # Automatically include type hints in docs
-sphinx-autoapi = "^3.0.0"           # Automatically generates API documentation
-myst-parser = "^2.0.0"              # Support for Markdown files in documentation
-
-# =============================================================================
-# COMMAND LINE SCRIPTS
-# =============================================================================
-# Define command-line entry points for your package
-#[tool.poetry.scripts]
-# Example:
-# your-command = "your_project_name.cli:main"  # Creates 'your-command' executable
-
-# =============================================================================
-# PROJECT URLS FOR PYPI
-# =============================================================================
-# Additional URLs that will be displayed on your PyPI project page
-#[tool.poetry.urls]
-#"Bug Tracker" = "https://github.com/mhofmann-Khoury/knit-graphs/issues"
-#"Changelog" = "https://github.com/mhofmann-Khoury/knit-graphs/blob/main/CHANGELOG.md"
-#"Discussions" = "https://github.com/your-username/your-project-name/discussions"
-
 # =============================================================================
 # ISORT IMPORT SORTER CONFIGURATION
 # =============================================================================

{knit_graphs-0.0.9 → knit_graphs-0.0.10}/src/knit_graphs/Knit_Graph.py

@@ -18,9 +18,6 @@ from knit_graphs.Loop import Loop
 from knit_graphs.Pull_Direction import Pull_Direction
 from knit_graphs.Yarn import Yarn
 
-# from knit_graphs.artin_wale_braids.Wale import Wale
-# from knit_graphs.artin_wale_braids.Wale_Group import Wale_Group
-
 
 class Knit_Graph:
     """A representation of knitted structures as connections between loops on yarns.
@@ -77,6 +74,42 @@ class Knit_Graph:
         if self._last_loop is None or loop > self._last_loop:
             self._last_loop = loop
 
+    def remove_loop(self, loop: Loop) -> None:
+        """
+        Remove the given loop from the knit graph.
+        Args:
+            loop (Loop): The loop to be removed.
+
+        Raises:
+            KeyError: If the loop is not in the knit graph.
+
+        """
+        if loop not in self:
+            raise KeyError(f"Loop {loop} not on the knit graph")
+        self.braid_graph.remove_loop(loop)  # remove any crossing associated with this loop.
+        # Remove any stitch edges involving this loop.
+        loop.remove_parent_loops()
+        if self.has_child_loop(loop):
+            child_loop = self.get_child_loop(loop)
+            assert isinstance(child_loop, Loop)
+            child_loop.remove_parent(loop)
+        self.stitch_graph.remove_node(loop)
+        # Remove loop from any floating positions
+        loop.remove_loop_from_front_floats()
+        loop.remove_loop_from_back_floats()
+        # 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
+                assert len(self.stitch_graph.nodes) == 0
+                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 isinstance(y.last_loop, Loop))
+
     def add_yarn(self, yarn: Yarn) -> None:
         """Add a yarn to the graph without adding its loops.
 
@@ -106,44 +139,31 @@ class Knit_Graph:
         self.stitch_graph.add_edge(parent_loop, child_loop, pull_direction=pull_direction)
         child_loop.add_parent_loop(parent_loop, stack_position)
 
-    def get_wale_starting_with_loop(self, first_loop: Loop) -> Wale:
-        """Get a wale (vertical column of stitches) starting from the specified loop.
+    def get_wales_ending_with_loop(self, last_loop: Loop) -> set[Wale]:
+        """Get all wales (vertical columns of stitches) that end at the specified loop.
 
         Args:
-            first_loop (Loop): The loop at the start of the wale to be constructed.
+            last_loop (Loop): The last loop of the joined set of wales.
 
         Returns:
-            Wale: A wale object representing the vertical column of stitches starting from the given loop.
+            set[Wale]: The set of wales that end at this loop.
         """
-        wale = Wale(first_loop)
-        cur_loop = first_loop
-        while len(self.stitch_graph.successors(cur_loop)) == 1:
-            cur_loop = [*self.stitch_graph.successors(cur_loop)][0]
-            assert isinstance(wale.last_loop, Loop)
-            wale.add_loop_to_end(cur_loop, self.get_pull_direction(wale.last_loop, cur_loop))
-        return wale
-
-    def get_wales_ending_with_loop(self, last_loop: Loop) -> list[Wale]:
-        """Get all wales (vertical columns of stitches) that end at the specified loop.
+        if len(last_loop.parent_loops) == 0:
+            return {Wale(last_loop, self)}
+        ancestors = last_loop.ancestor_loops()
+        return {Wale(l, self) for l in ancestors}
 
-        Args:
-            last_loop (Loop): The last loop of the joined set of wales.
+    def get_terminal_wales(self) -> dict[Loop, list[Wale]]:
+        """
+        Get wale groups organized by their terminal loops.
 
         Returns:
-            list[Wale]: The set of wales that end at this loop. Only returns multiple wales if this loop is a child of a decrease stitch.
+            dict[Loop, list[Wale]]: Dictionary mapping terminal loops to list of wales that terminate that wale.
         """
-        wales = []
-        if len(last_loop.parent_loops) == 0:
-            return [Wale(last_loop)]
-        for top_stitch_parent in last_loop.parent_loops:
-            wale = Wale(last_loop)
-            wale.add_loop_to_beginning(top_stitch_parent, cast(Pull_Direction, self.get_pull_direction(top_stitch_parent, last_loop)))
-            cur_loop = top_stitch_parent
-            while len(cur_loop.parent_loops) == 1:  # stop at split for decrease or start of wale
-                cur_loop = cur_loop.parent_loops[0]
-                wale.add_loop_to_beginning(cur_loop, cast(Pull_Direction, self.get_pull_direction(cur_loop, cast(Loop, wale.first_loop))))
-            wales.append(wale)
-        return wales
+        wale_groups = {}
+        for loop in self.terminal_loops():
+            wale_groups[loop] = [wale for wale in self.get_wales_ending_with_loop(loop)]
+        return wale_groups
 
     def get_courses(self) -> list[Course]:
         """Get all courses (horizontal rows) in the knit graph in chronological order.
@@ -164,17 +184,13 @@ class Knit_Graph:
         courses.append(course)
         return courses
 
-    def get_wale_groups(self) -> dict[Loop, Wale_Group]:
+    def get_wale_groups(self) -> set[Wale_Group]:
         """Get wale groups organized by their terminal loops.
 
         Returns:
-            dict[Loop, Wale_Group]: Dictionary mapping terminal loops to the wale groups they terminate. Each wale group represents a collection of wales that end at the same terminal loop.
+            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.
         """
-        wale_groups = {}
-        for loop in self:
-            if self.is_terminal_loop(loop):
-                wale_groups.update({loop: Wale_Group(wale, self) for wale in self.get_wales_ending_with_loop(loop)})
-        return wale_groups
+        return set(Wale_Group(l, self) for l in self.terminal_loops())
 
     def __contains__(self, item: Loop | tuple[Loop, Loop]) -> bool:
         """Check if a loop is contained in the knit graph.
@@ -197,6 +213,12 @@ class Knit_Graph:
         """
         return cast(Iterator[Loop], iter(self.stitch_graph.nodes))
 
+    def __getitem__(self, item: int) -> Loop:
+        loop = next((l for l in self if l.loop_id == item), None)
+        if loop is None:
+            raise KeyError(f"Loop of id {item} not in knit graph")
+        return loop
+
     def sorted_loops(self) -> list[Loop]:
         """
         Returns:
@@ -270,3 +292,10 @@ class Knit_Graph:
             bool: True if the loop has no child loops and terminates a wale, False otherwise.
         """
         return not self.has_child_loop(loop)
+
+    def terminal_loops(self) -> Iterator[Loop]:
+        """
+        Returns:
+            Iterator[Loop]: An iterator over all terminal loops in the knit graph.
+        """
+        return iter(l for l in self if self.is_terminal_loop(l))

{knit_graphs-0.0.9 → knit_graphs-0.0.10}/src/knit_graphs/Loop.py

@@ -5,7 +5,7 @@ Loops are the fundamental building blocks of knitted structures and maintain rel
 """
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, cast
+from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from knit_graphs.Yarn import Yarn
@@ -47,7 +47,12 @@ class Loop:
         Args:
             u (Loop): The first loop in the float pair.
             v (Loop): The second loop in the float pair.
+
+        Raises:
+            ValueError: If u and v are not on the same yarn.
         """
+        if u.yarn != v.yarn:
+            raise ValueError("Loops of a float must share a yarn.")
         if u not in self.back_floats:
             self.back_floats[u] = set()
         if v not in self.back_floats:
@@ -55,6 +60,18 @@ class Loop:
         self.back_floats[u].add(v)
         self.back_floats[v].add(u)
 
+    def remove_loop_from_front_floats(self) -> None:
+        """
+        Removes this loop from being in front of all marked floats. Mutates the yarns that own edges of those floats.
+        """
+        visited: set[Loop] = set()
+        for u, v_loops in self.front_floats.items():
+            visited.add(u)
+            for v in v_loops:
+                if v not in visited and v in u.yarn:  # float shares a yarn
+                    u.yarn.loop_graph.edges[u, v]["Back_Loops"].remove(self)
+        self.front_floats = {}
+
     def add_loop_behind_float(self, u: Loop, v: Loop) -> None:
         """Set this loop to be behind the float between loops u and v.
 
@@ -63,7 +80,12 @@ class Loop:
         Args:
             u (Loop): The first loop in the float pair.
             v (Loop): The second loop in the float pair.
+
+        Raises:
+            ValueError: If u and v are not on the same yarn.
         """
+        if u.yarn != v.yarn:
+            raise ValueError("Loops of a float must share a yarn.")
         if u not in self.front_floats:
             self.front_floats[u] = set()
         if v not in self.front_floats:
@@ -71,6 +93,18 @@ class Loop:
         self.front_floats[u].add(v)
         self.front_floats[v].add(u)
 
+    def remove_loop_from_back_floats(self) -> None:
+        """
+        Removes this loop from being behind of all marked floats. Mutates the yarns that own edges of those floats.
+        """
+        visited = set()
+        for u, v_loops in self.back_floats.items():
+            visited.add(u)
+            for v in v_loops:
+                if v not in visited and v in u.yarn:  # float shares a yarn
+                    u.yarn.loop_graph.edges[u, v]["Front_Loops"].remove(self)
+        self.back_floats = {}
+
     def is_in_front_of_float(self, u: Loop, v: Loop) -> bool:
         """Check if this loop is positioned in front of the float between loops u and v.
 
@@ -101,19 +135,25 @@ class Loop:
         Returns:
             Loop | None: The prior loop on the yarn, or None if this is the first loop on the yarn.
         """
-        loop = self.yarn.prior_loop(self)
-        if loop is None:
-            return None
-        else:
-            return loop
+        return self.yarn.prior_loop(self)
 
-    def next_loop_on_yarn(self) -> Loop:
+    def next_loop_on_yarn(self) -> Loop | None:
         """Get the loop that follows this loop on the same yarn.
 
         Returns:
-            Loop: The next loop on the yarn, or None if this is the last loop on the yarn.
+            Loop | None: The next loop on the yarn, or None if this is the last loop on the yarn.
         """
-        return cast(Loop, self.yarn.next_loop(self))
+        return self.yarn.next_loop(self)
+
+    def remove_parent_loops(self) -> list[Loop]:
+        """
+        Removes the list of parent loops from this loop.
+        Returns:
+            list[Loop]: The list of parent loops that were removed.
+        """
+        parents = self.parent_loops
+        self.parent_loops = []
+        return parents
 
     def has_parent_loops(self) -> bool:
         """Check if this loop has any parent loops connected through stitch edges.
@@ -135,6 +175,31 @@ class Loop:
         else:
             self.parent_loops.append(parent)
 
+    def remove_parent(self, parent: Loop) -> None:
+        """
+        Removes the given parent loop from the set of parents of this loop.
+        If the given loop is not a parent of this loop, nothing happens.
+        Args:
+            parent (Loop): The parent loop to remove.
+        """
+        if parent in self.parent_loops:
+            self.parent_loops.remove(parent)
+
+    def ancestor_loops(self) -> set[Loop]:
+        """
+        Returns:
+            set[Loop]: The set of loops that initiate all wales that lead to this loop. The empty set if this loop has no parents.
+        """
+        if not self.has_parent_loops():
+            return set()
+        ancestors = set()
+        for parent_loop in self.parent_loops:
+            if parent_loop.has_parent_loops():
+                ancestors.update(parent_loop.ancestor_loops())
+            else:
+                ancestors.add(parent_loop)
+        return ancestors
+
     @property
     def loop_id(self) -> int:
         """Get the unique identifier of this loop.

{knit_graphs-0.0.9 → knit_graphs-0.0.10}/src/knit_graphs/Yarn.py

@@ -82,6 +82,8 @@ class Yarn:
         loop_graph (DiGraph): The directed graph loops connected by yarn-wise float edges.
         properties (Yarn_Properties): The physical and visual properties of this yarn.
     """
+    FRONT_LOOPS: str = "Front_Loops"
+    _BACK_LOOPS: str = "Back_Loops"
 
     def __init__(self, yarn_properties: None | Yarn_Properties = None, knit_graph: None | Knit_Graph = None):
         """Initialize a yarn with the specified properties and optional knit graph association.
@@ -141,7 +143,7 @@ class Yarn:
                 self.add_loop_in_front_of_float(front_loop, v, u)
             else:
                 return
-        self.loop_graph.edges[u, v]["Front_Loops"].add(front_loop)
+        self.loop_graph.edges[u, v][self.FRONT_LOOPS].add(front_loop)
         front_loop.add_loop_in_front_of_float(u, v)
 
     def add_loop_behind_float(self, back_loop: Loop, u: Loop, v: Loop) -> None:
@@ -157,7 +159,7 @@ class Yarn:
                 self.add_loop_behind_float(back_loop, v, u)
             else:
                 return
-        self.loop_graph.edges[u, v]["Back_Loops"].add(back_loop)
+        self.loop_graph.edges[u, v][self._BACK_LOOPS].add(back_loop)
         back_loop.add_loop_behind_float(u, v)
 
     def get_loops_in_front_of_float(self, u: Loop, v: Loop) -> set[Loop]:
@@ -176,7 +178,7 @@ class Yarn:
             else:
                 return set()
         else:
-            return cast(set[Loop], self.loop_graph.edges[u, v]['Front_Loops'])
+            return cast(set[Loop], self.loop_graph.edges[u, v][self.FRONT_LOOPS])
 
     def get_loops_behind_float(self, u: Loop, v: Loop) -> set[Loop]:
         """Get all loops positioned behind the float between two loops.
@@ -194,7 +196,7 @@ class Yarn:
             else:
                 return set()
         else:
-            return cast(set[Loop], self.loop_graph.edges[u, v]['Back_Loops'])
+            return cast(set[Loop], self.loop_graph.edges[u, v][self._BACK_LOOPS])
 
     @property
     def last_loop(self) -> Loop | None:
@@ -290,6 +292,41 @@ class Yarn:
         else:
             return self.last_loop.loop_id + 1
 
+    def remove_loop(self, loop: Loop) -> None:
+        """
+        Remove the given loop from the yarn.
+        Reconnects any neighboring loops to form a new float with the positioned in-front-of or behind the original floats positioned accordingly.
+        Resets the first_loop and last_loop properties if the removed loop was the tail of the yarn.
+        Args:
+            loop (Loop): The loop to remove from the yarn.
+
+        Raises:
+            KeyError: The given loop does not exist in the yarn.
+        """
+        if loop not in self:
+            raise KeyError(f'Loop {loop} does not exist on yarn {self}.')
+        prior_loop = self.prior_loop(loop)
+        next_loop = self.next_loop(loop)
+        if isinstance(prior_loop, Loop) and isinstance(next_loop, Loop):  # Loop is between two floats to be merged.
+            front_of_float_loops = self.get_loops_in_front_of_float(prior_loop, loop)
+            front_of_float_loops.update(self.get_loops_in_front_of_float(loop, next_loop))
+            back_of_float_loops = self.get_loops_behind_float(prior_loop, loop)
+            back_of_float_loops.update(self.get_loops_behind_float(loop, next_loop))
+            self.loop_graph.remove_node(loop)
+            self.loop_graph.add_edge(prior_loop, next_loop, Front_Loops=front_of_float_loops, Back_Loops=back_of_float_loops)
+            for front_loop in front_of_float_loops:
+                front_loop.add_loop_in_front_of_float(prior_loop, next_loop)
+            for back_loop in back_of_float_loops:
+                back_loop.add_loop_behind_float(prior_loop, next_loop)
+            return
+        if next_loop is None:  # This was the last loop, make the prior loop the last loop.
+            assert loop is self.last_loop
+            self._last_loop = prior_loop
+        if prior_loop is None:  # This was the first loop, make the next loop the first loop.
+            assert loop is self.first_loop
+            self._first_loop = next_loop
+        self.loop_graph.remove_node(loop)
+
     def add_loop_to_end(self, loop: Loop) -> Loop:
         """Add an existing loop to the end of this yarn and associated knit graph.
 

{knit_graphs-0.0.9 → knit_graphs-0.0.10}/src/knit_graphs/artin_wale_braids/Loop_Braid_Graph.py

@@ -19,6 +19,7 @@ class Loop_Braid_Graph:
     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."""
@@ -34,6 +35,15 @@ class Loop_Braid_Graph:
         """
         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.
+        """
+        if loop in self:
+            self.loop_crossing_graph.remove_node(loop)
+
     def __contains__(self, item: Loop | tuple[Loop, Loop]) -> bool:
         """Check if a loop or loop pair is contained in the braid graph.
 
@@ -92,4 +102,4 @@ class Loop_Braid_Graph:
         """
         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'])
+        return cast(Crossing_Direction, self.loop_crossing_graph[left_loop][right_loop][self._CROSSING])

{knit_graphs-0.0.9 → knit_graphs-0.0.10}/src/knit_graphs/artin_wale_braids/Wale.py

@@ -4,13 +4,16 @@ This module defines the Wale class which represents a vertical column of stitche
 """
 from __future__ import annotations
 
-from typing import Iterator, cast
+from typing import TYPE_CHECKING, Iterator, cast
 
 from networkx import DiGraph, dfs_preorder_nodes
 
 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
+
 
 class Wale:
     """A data structure representing stitch relationships between loops in a vertical column of a knitted structure.
@@ -23,49 +26,42 @@ class Wale:
         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 | None = None) -> None:
+    def __init__(self, first_loop: Loop, knit_graph: Knit_Graph, end_loop: Loop | None = None) -> None:
         """Initialize a wale optionally starting with a specified loop.
 
         Args:
-            first_loop (Loop | None, optional): The initial loop to start the wale with. If provided, it will be added as both the first and last loop. Defaults to None.
+            first_loop (Loop): The initial loop to start the wale with.
+            knit_graph (Knit_Graph): The knit graph that owns this wale.
+            end_loop (Loop, optional):
+                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.first_loop: None | Loop = first_loop
-        self.last_loop: None | Loop = None
-        if isinstance(self.first_loop, Loop):
-            self.add_loop_to_end(self.first_loop, pull_direction=None)
-
-    def add_loop_to_end(self, loop: Loop, pull_direction: Pull_Direction | None = Pull_Direction.BtF) -> None:
-        """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.
-            pull_direction (Pull_Direction | None, optional): The direction to pull the loop through its parent loop. Defaults to Pull_Direction.BtF. Can be None only for the first loop in the wale.
+        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
+        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:
         """
-        if self.last_loop is None:
-            self.stitches.add_node(loop)
-            self.first_loop = loop
-            self.last_loop = loop
-        else:
-            assert isinstance(pull_direction, Pull_Direction)
-            self.stitches.add_edge(self.last_loop, loop, pull_direction=pull_direction)
-            self.last_loop = loop
-
-    def add_loop_to_beginning(self, loop: Loop, pull_direction: Pull_Direction = Pull_Direction.BtF) -> None:
-        """Add a loop to the beginning (bottom) of the wale with the specified pull direction.
+        Add a loop to the end (top) of the wale with the specified pull direction.
 
         Args:
-            loop (Loop): The loop to add to the beginning of the wale.
-            pull_direction (Pull_Direction, optional): The direction to pull the existing first loop through this new loop. Defaults to Pull_Direction.BtF.
+            loop (Loop): The loop to add to the end of the wale.
         """
-        if self.first_loop is None:
-            self.stitches.add_node(loop)
-            self.first_loop = loop
-            self.last_loop = loop
-        else:
-            self.stitches.add_edge(loop, self.first_loop, pull_direction=pull_direction)
-            self.first_loop = loop
+        self.stitches.add_edge(self.last_loop, loop, pull_direction=self._knit_graph.get_pull_direction(self.last_loop, loop))
+        self.last_loop = loop
 
     def get_stitch_pull_direction(self, u: Loop, v: Loop) -> Pull_Direction:
         """Get the pull direction of the stitch edge between two loops in this wale.
@@ -77,10 +73,11 @@ class Wale:
         Returns:
             Pull_Direction: The pull direction of the stitch between loops u and v.
         """
-        return cast(Pull_Direction, self.stitches.edges[u, v]["pull_direction"])
+        return cast(Pull_Direction, self.stitches.edges[u, v][self._PULL_DIRECTION])
 
     def split_wale(self, split_loop: Loop) -> tuple[Wale, Wale | None]:
-        """Split this wale at the specified loop into two separate wales.
+        """
+        Split this wale at the specified loop into two separate wales.
 
         The split loop becomes the last loop of the first wale and the first loop of the second wale.
 
@@ -93,19 +90,23 @@ class Wale:
                 * 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.
         """
-        first_wale = Wale(self.first_loop)
-        growing_wale = first_wale
-        found_loop = False
-        for l in cast(list[Loop], self[1:]):
-            if l is split_loop:
-                growing_wale.add_loop_to_end(l, self.get_stitch_pull_direction(cast(Loop, growing_wale.last_loop), l))
-                growing_wale = Wale(split_loop)
-                found_loop = True
-            else:
-                growing_wale.add_loop_to_end(l, self.get_stitch_pull_direction(cast(Loop, growing_wale.last_loop), l))
-        if not found_loop:
+        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))
+        else:
             return self, None
-        return first_wale, growing_wale
+
+    def __eq__(self, other: Wale) -> bool:
+        """
+        Args:
+            other (Wale): The wale to compare.
+
+        Returns:
+            bool: True if all the loops in both wales are present and in the same order. False, otherwise.
+        """
+        if len(self) != len(other):
+            return False
+        return not any(l != o for l, o in zip(self, other))
 
     def __len__(self) -> int:
         """Get the number of loops in this wale.
@@ -149,13 +150,28 @@ class Wale:
         return bool(self.stitches.has_node(item))
 
     def __hash__(self) -> int:
-        """Get the hash value of this wale based on its first loop.
+        """
+        Get the hash value of this wale based on its first loop.
 
         Returns:
             int: Hash value based on the first loop in this wale.
         """
         return hash(self.first_loop)
 
+    def __str__(self) -> str:
+        """
+        Returns:
+            str: The string representation of this wale.
+        """
+        return f"Wale({self.first_loop}->{self.last_loop})"
+
+    def __repr__(self) -> str:
+        """
+        Returns:
+            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.
 

{knit_graphs-0.0.9 → knit_graphs-0.0.10}/src/knit_graphs/artin_wale_braids/Wale_Group.py

@@ -24,84 +24,66 @@ 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.
-        terminal_wale (Wale | None): The topmost wale in this group, typically where multiple wales converge.
         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_wale: Wale, knit_graph: Knit_Graph):
+    def __init__(self, terminal_loop: Loop, knit_graph: Knit_Graph):
         """Initialize a wale group starting from a terminal wale and building downward.
 
         Args:
-            terminal_wale (Wale): The topmost wale in the group, used as the starting point for building the complete group structure.
+            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.
         """
         self.wale_graph: DiGraph = DiGraph()
         self.stitch_graph: DiGraph = DiGraph()
         self._knit_graph: Knit_Graph = knit_graph
-        self.terminal_wale: Wale | None = terminal_wale
+        self._terminal_loop: Loop = terminal_loop
         self.top_loops: dict[Loop, Wale] = {}
         self.bottom_loops: dict[Loop, Wale] = {}
-        self.build_group_from_top_wale(terminal_wale)
+        self._build_wale_group()
 
-    def add_wale(self, wale: Wale) -> None:
-        """Add a wale to the group and connect it to existing wales through shared loops.
-
-        This method adds the wale to the group's graphs and establishes connections with other wales based on shared loops at their endpoints.
-
-        Args:
-            wale (Wale): The wale to add to this group. Empty wales are ignored and not added.
+    @property
+    def terminal_loop(self) -> Loop:
+        """
+        Returns:
+            Loop: The loop that terminates all wales in this group.
         """
-        if len(wale) == 0:
-            return  # This wale is empty and therefore there is nothing to add to the wale group
+        return self._terminal_loop
+
+    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:])
+            for u, v in zip(u_loops, v_loops):
+                self.stitch_graph.add_edge(u, v, pull_direction=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:])
+            for loop in upper_loops:  # skip first loop in each wale as it may be already connected to a discovered decrease.
+                if len(loop.parent_loops) > 1:  # Focal of a decrease.
+                    clean_wale, remaining_wale = wale_to_split.split_wale(loop)
+                    if not self.wale_graph.has_node(clean_wale):
+                        self._add_wale(clean_wale)
+                    if isinstance(remaining_wale, Wale):
+                        wales_to_split.add(remaining_wale)
+                    split = True
+                    break
+            if not split:
+                self._add_wale(wale_to_split)
+        for bot_loop, lower_wale in self.bottom_loops.items():
+            if lower_wale.last_loop in self.bottom_loops:
+                self.wale_graph.add_edge(lower_wale, self.bottom_loops[lower_wale.last_loop])
+
+    def _add_wale(self, wale: Wale) -> None:
         self.wale_graph.add_node(wale)
-        for u, v in wale.stitches.edges:
-            self.stitch_graph.add_edge(u, v, pull_direction=wale.get_stitch_pull_direction(u, v))
-        for top_loop, other_wale in self.top_loops.items():
-            if top_loop == wale.first_loop:
-                self.wale_graph.add_edge(other_wale, wale)
-        for bot_loop, other_wale in self.bottom_loops.items():
-            if bot_loop == wale.last_loop:
-                self.wale_graph.add_edge(wale, other_wale)
-        assert isinstance(wale.last_loop, Loop)
         self.top_loops[wale.last_loop] = wale
-        assert isinstance(wale.first_loop, Loop)
         self.bottom_loops[wale.first_loop] = wale
 
-    def add_parent_wales(self, wale: Wale) -> list[Wale]:
-        """Find and add all parent wales that created the given wale through decrease operations.
-
-        This method identifies wales that end at the loops that are parents of this wale's first loop, representing the wales that were decreased together to form the given wale.
-
-        Args:
-            wale (Wale): The wale to find and add parent wales for.
-
-        Returns:
-            list[Wale]: The list of parent wales that were found and added to the group.
-        """
-        added_wales = []
-        for parent_loop in cast(Loop, wale.first_loop).parent_loops:
-            parent_wales = self._knit_graph.get_wales_ending_with_loop(parent_loop)
-            for parent_wale in parent_wales:
-                self.add_wale(parent_wale)
-            added_wales.extend(parent_wales)
-        return added_wales
-
-    def build_group_from_top_wale(self, top_wale: Wale) -> None:
-        """Build the complete wale group by recursively finding all parent wales from the terminal wale.
-
-        This method starts with the terminal wale and recursively adds all parent wales, building the complete tree structure of wales that contribute to the terminal wale through decrease operations.
-
-        Args:
-            top_wale (Wale): The terminal wale at the top of the group structure.
-        """
-        self.add_wale(top_wale)
-        added_wales = self.add_parent_wales(top_wale)
-        while len(added_wales) > 0:
-            next_wale = added_wales.pop()
-            more_wales = self.add_parent_wales(next_wale)
-            added_wales.extend(more_wales)
-
     def get_loops_over_courses(self) -> list[list[Loop]]:
         """Get loops organized by their course (horizontal row) within this wale group.
 
@@ -110,11 +92,8 @@ class Wale_Group:
         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.
         """
-        if self.terminal_wale is None:
-            return []
-        top_loop: Loop = cast(Loop, self.terminal_wale.last_loop)
         courses: list[list[Loop]] = []
-        cur_course: list[Loop] = [top_loop]
+        cur_course: list[Loop] = [self._terminal_loop]
         while len(cur_course) > 0:
             courses.append(cur_course)
             next_course = []
@@ -136,3 +115,37 @@ class Wale_Group:
             path_len = sum(len(successor) for successor in dfs_preorder_nodes(self.wale_graph, wale))
             max_len = max(max_len, path_len)
         return max_len
+
+    def __hash__(self) -> int:
+        """
+        Returns:
+            int: Hash value of the terminal loop of this group.
+        """
+        return hash(self._terminal_loop)
+
+    def __contains__(self, item: Loop | int | Wale) -> bool:
+        """
+        Args:
+            item (Loop | 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.
+        """
+        if isinstance(item, Loop) or isinstance(item, int):
+            return item in self.stitch_graph.nodes
+        else:  # isinstance(item, Wale):
+            return item in self.wale_graph
+
+    def __str__(self) -> str:
+        """
+        Returns:
+            str: The string representation of this wale group.
+        """
+        return f"WG({self.terminal_loop})"
+
+    def __repr__(self) -> str:
+        """
+        Returns:
+            str: The string representation of this wale group.
+        """
+        return str(self)