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

knit_graphs/artin_wale_braids/Wale.py

@@ -1,93 +1,169 @@
-"""Module containing the Wale Class"""
-import networkx
-
-from knit_graphs.Loop import Loop
-from knit_graphs.Pull_Direction import Pull_Direction
-
-
-class Wale:
-    """
-        Data structure representing stitch relationships between loops in a knitted structure
-    """
-
-    def __init__(self, first_loop: None | Loop = None):
-        self.stitches: networkx.DiGraph = networkx.DiGraph()
-        self.first_loop: None | Loop = first_loop
-        self.last_loop: None | Loop = first_loop
-
-    def add_loop_to_end(self, loop: Loop, pull_direction: Pull_Direction = Pull_Direction.BtF):
-        """
-        Adds loop onto stitch graph with edge value of given pull_direction. Assumes loop comes after last loop.
-        :param loop: Loop to add to the end of wale.
-        :param pull_direction: Direction to pull loop through parent loop.
-        """
-        if self.last_loop is None:
-            self.stitches.add_node(loop)
-            self.first_loop = loop
-            self.last_loop = loop
-        else:
-            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):
-        """
-        Adds loop onto stitch graph with edge value of given pull_direction. Assumes loop comes before first loop.
-        :param loop: Loop to add to the beginning of wale.
-        :param pull_direction: Direction to pull loop through child loop.
-        """
-        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
-
-    def get_stitch_pull_direction(self, u: Loop, v: Loop) -> Pull_Direction:
-        """
-        :param u:
-        :param v:
-        :return: The Pull direction of stitch between loops u and v
-        """
-        return self.stitches.edges[u, v]["pull_direction"]
-
-    def split_wale(self, split_loop: Loop) -> tuple:
-        """
-        :param split_loop: loop to split at. Will be the first loop in the second wale and last loop in the first wale
-        :return: tuple of wales or current wale and none if loop not found
-        """
-        first_wale = Wale(self.first_loop)
-        growing_wale = first_wale
-        found_loop = False
-        for l in self[1:]:
-            if l is split_loop:
-                growing_wale.add_loop_to_end(l, self.get_stitch_pull_direction(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(growing_wale.last_loop, l))
-        if not found_loop:
-            return self, None
-        return first_wale, growing_wale
-
-    def __len__(self):
-        return len(self.stitches.nodes)
-
-    def __iter__(self):
-        return networkx.dfs_preorder_nodes(self.stitches, source=self.first_loop)
-
-    def __contains__(self, item: Loop):
-        return self.stitches.has_node(item)
-
-    def __hash__(self):
-        return hash(self.first_loop)
-
-    def overlaps(self, other):
-        """
-        :param other: Wale to compare against.
-        :return: True if the other wale has overlapping loop(s) with this wale.
-        """
-        for loop in self:
-            if loop in other:
-                return True
-        return False
+"""Module containing the Wale Class.
+
+This module defines the Wale class which represents a vertical column of stitches in a knitted structure, maintaining the sequence and relationships between loops in that column.
+"""
+from __future__ import annotations
+
+from typing import Iterator, cast
+
+from networkx import dfs_preorder_nodes
+
+from knit_graphs._base_classes import _Base_Wale
+from knit_graphs.Loop import Loop
+from knit_graphs.Pull_Direction import Pull_Direction
+
+
+class Wale(_Base_Wale):
+    """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.
+    This class manages the sequential relationships between loops and tracks the pull directions of stitches within the 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.
+    """
+
+    def __init__(self, first_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.
+        """
+        super().__init__()
+        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.
+        """
+        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.
+
+        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.
+        """
+        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
+
+    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.
+
+        Args:
+            u (Loop): The parent loop in the stitch connection.
+            v (Loop): 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]["pull_direction"])
+
+    def split_wale(self, split_loop: Loop) -> tuple[Wale, Wale | None]:
+        """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.
+
+        Args:
+            split_loop (Loop): The loop at which to split the wale. This loop will appear in both resulting wales.
+
+        Returns:
+            tuple[Wale, Wale | 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.
+        """
+        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:
+            return self, None
+        return first_wale, growing_wale
+
+    def __len__(self) -> int:
+        """Get the number of loops in this wale.
+
+        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.
+
+        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))
+
+    def __getitem__(self, item: int | slice) -> Loop | list[Loop]:
+        """Get loop(s) at the specified index or slice within this wale.
+
+        Args:
+            item (int | slice): The index of a single loop or a slice for multiple loops.
+
+        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.
+
+        Returns:
+            bool: True if the loop is in this wale, False otherwise.
+        """
+        return bool(self.stitches.has_node(item))
+
+    def __hash__(self) -> int:
+        """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 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

@@ -1,30 +1,50 @@
-"""Model of knitted structure as a set of crossing wales using artin braid groups"""
-from knit_graphs.artin_wale_braids.Wale_Braid_Word import Wale_Braid_Word
-from knit_graphs.artin_wale_braids.Wale_Group import Wale_Group
-
-
-class Wale_Braid:
-    """
-        Models a knitted structure as a set of crossing wales using artin braid groups
-    """
-    def __init__(self, wale_groups: list[Wale_Group], wale_words: list[Wale_Braid_Word]):
-        self.wale_groups: list[Wale_Group] = wale_groups
-        self.wale_words: list[Wale_Braid_Word] = wale_words
-
-    def reduce(self):
-        """
-           Modifies wale_words by removing any braid words that invert each other
-        """
-        reduced_words: list[Wale_Braid_Word] = []
-        remaining_words: list[Wale_Braid_Word] = [*self.wale_words[1:]]
-        while len(remaining_words) > 0:
-            if len(reduced_words) == 0:
-                reduced_words.append(remaining_words.pop(0))
-            else:
-                next_word = remaining_words.pop(0)
-                current_word = reduced_words[-1]
-                if next_word.is_inversion(current_word):
-                    reduced_words.pop()  # remove current word because its inverted
-                else:
-                    reduced_words.append(next_word)
-        self.wale_words = reduced_words
+"""Model of knitted structure as a set of crossing wales using artin braid groups.
+
+This module provides the Wale_Braid class which represents complex cable knitting patterns as mathematical braid structures,
+using concepts from algebraic topology to model how wales cross over and under each other.
+"""
+from knit_graphs.artin_wale_braids.Wale_Braid_Word import Wale_Braid_Word
+from knit_graphs.artin_wale_braids.Wale_Group import Wale_Group
+
+
+class Wale_Braid:
+    """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,
+    where wales are treated as strands in a braid and their crossings are represented as braid operations.
+    This provides a formal mathematical framework for analyzing and manipulating cable patterns.
+
+    Attributes:
+        wale_groups (list[Wale_Group]): The collection of wale groups that participate in the braid structure.
+        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:
+        """Initialize a wale braid with the specified groups and braid words.
+
+        Args:
+            wale_groups (list[Wale_Group]): The wale groups that participate in this braid structure.
+            wale_words (list[Wale_Braid_Word]): The sequence of braid words describing the crossing operations.
+        """
+        self.wale_groups: list[Wale_Group] = wale_groups
+        self.wale_words: list[Wale_Braid_Word] = wale_words
+
+    def reduce(self) -> None:
+        """Simplify the braid by removing pairs of braid words that invert each other.
+
+        This method modifies the wale_words list by identifying and removing adjacent pairs of braid words that are inverses of each other,
+         effectively canceling out their operations to create a simplified but equivalent braid representation.
+        """
+        reduced_words: list[Wale_Braid_Word] = []
+        remaining_words: list[Wale_Braid_Word] = [*self.wale_words[1:]]
+        while len(remaining_words) > 0:
+            if len(reduced_words) == 0:
+                reduced_words.append(remaining_words.pop(0))
+            else:
+                next_word = remaining_words.pop(0)
+                current_word = reduced_words[-1]
+                if next_word.is_inversion(current_word):
+                    reduced_words.pop()  # remove current word because its inverted
+                else:
+                    reduced_words.append(next_word)
+        self.wale_words = reduced_words

knit_graphs/artin_wale_braids/Wale_Braid_Word.py

@@ -1,54 +1,99 @@
-"""Module contianing the Wale Braid Word Class"""
-
-from knit_graphs.Loop import Loop
-from knit_graphs.artin_wale_braids.Crossing_Direction import Crossing_Direction
-
-
-class Wale_Braid_Word:
-    """
-       Representation of loop crossings over a set of loops in a common course
-    """
-    def __init__(self, loops: list[Loop], crossings: dict[int, Crossing_Direction]):
-        self.loops: list[Loop] = loops
-        self.crossings: dict[int, Crossing_Direction] = crossings
-
-    def new_loop_order(self) -> list[Loop]:
-        """
-        :return: list of loops in order that results from applying the crossing operations
-        """
-        new_loops: list[Loop] = [*self.loops]
-        for i in sorted(self.crossings.keys(), reverse=True):
-            moves_left = new_loops[i + 1]
-            new_loops[i + 1] = new_loops[i]
-            new_loops[i] = moves_left
-
-        return new_loops
-
-    def __invert__(self):
-        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)
-
-    def __eq__(self, other):
-        if not isinstance(other, Wale_Braid_Word):
-            return False
-        for l, o in zip(self.loops, other.loops):
-            if l != o:
-                return False
-        for i, cd in self.crossings.items():
-            if i not in other.crossings:
-                return False
-            if other.crossings[i] != cd:
-                return False
-        return True
-
-    def is_inversion(self, other) -> bool:
-        """
-        :param other: other braid word to compare to
-        :return: True if other is equal to inversion of self
-        """
-        invert = ~self
-        return other == invert
-
-    def __len__(self):
-        return len(self.loops)
+"""Module containing the Wale Braid Word Class.
+
+This module provides the Wale_Braid_Word class which represents a single step in a braid operation, describing how loops cross over each other within a course of knitting.
+"""
+from __future__ import annotations
+
+from knit_graphs.artin_wale_braids.Crossing_Direction import Crossing_Direction
+from knit_graphs.Loop import Loop
+
+
+class Wale_Braid_Word:
+    """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.
+        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:
+        """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.
+        """
+        self.loops: list[Loop] = loops
+        self.crossings: dict[int, Crossing_Direction] = crossings
+
+    def new_loop_order(self) -> list[Loop]:
+        """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.
+        Crossings are applied from right to left (highest index to lowest) to maintain proper braid semantics.
+
+        Returns:
+            list[Loop]: The list of loops in their new order after all crossing operations have been applied.
+        """
+        new_loops: list[Loop] = [*self.loops]
+        for i in sorted(self.crossings.keys(), reverse=True):
+            moves_left = new_loops[i + 1]
+            new_loops[i + 1] = new_loops[i]
+            new_loops[i] = moves_left
+
+        return new_loops
+
+    def __invert__(self) -> Wale_Braid_Word:
+        """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.
+        """
+        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)
+
+    def __eq__(self, other: Wale_Braid_Word) -> bool:
+        """Check equality with another wale braid word.
+
+        Two braid words are equal if they have the same loops in the same order and the same crossing operations at the same indices.
+
+        Args:
+            other (Wale_Braid_Word): The other braid word to compare with.
+
+        Returns:
+            bool: True if both braid words have identical loops, loop ordering, and crossing operations, False otherwise.
+        """
+        if (len(self) != len(other)
+                or any(l != o for l, o in zip(self.loops, other.loops))
+                or any(i not in other.crossings for i in self.crossings)
+                or any(other.crossings[i] != cd for i, cd in self.crossings.items())):
+            return False
+        else:
+            return True
+
+    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 __len__(self) -> int:
+        """Get the number of loops in this braid word.
+
+        Returns:
+            int: The total number of loops participating in this braid word.
+        """
+        return len(self.loops)