free_groups_26 1.2.0__py3-none-any.whl

free_groups_26/__init__.py

@@ -0,0 +1,44 @@
+__version__ = "1.2.0"
+
+from .letter import (
+    letter_from_str,
+    letter_from_str_b,
+    letter_from_str_a,
+    Letter,
+    Symbol,
+    Exponent,
+)
+from .word import (
+    word_from_str,
+    word_from_str_a,
+    word_from_str_b,
+    Word,
+    generate_random_word,
+    read,
+)
+from .free_group import FreeGroup, get_free_group
+from .morphism import Morphism
+from .whitehead_automorphism import (
+    generate_whitehead_automorphism_t2,
+    generate_all_t2_whitehead_automorphisms,
+    generate_t2_wh_aut_lazy,
+)
+from .minimize_bruteforce import (
+    minimize_once_bruteforce,
+    minimize_bruteforce,
+    minimize_once_bruteforce_lazy,
+)
+from .whitehead_graph import (
+    WhiteheadGraph,
+    generate_whg,
+    change_whg_edge_or_weight,
+    draw_graph,
+)
+from .whitehead_minimization import (
+    minimize_whitehead_once,
+    minimize_whitehead,
+    is_minimal,
+    type_1_minimize,
+)
+from .aut_orbit_bruteforce import find_minimal_automorphic_orbit
+from .log import Log, LogItem, new_log, display_log

free_groups_26/aut_orbit_bruteforce.py

@@ -0,0 +1,16 @@
+from warnings import warn
+from free_groups_26.morphism import Morphism
+from free_groups_26.whitehead_automorphism import generate_t2_wh_aut_lazy
+from free_groups_26.whitehead_minimization import is_minimal
+from free_groups_26.word import Word
+
+
+def find_minimal_automorphic_orbit(word: Word) -> list[tuple[Morphism, Word]]:
+    aut_list: list[tuple[Morphism, Word]] = []
+    if not is_minimal(word):
+        warn("Finding automorphic orbit of non-minimal word.")
+    for phi in generate_t2_wh_aut_lazy(word.infer_free_group()):
+        new_word = phi(word)
+        if new_word.length == word.length:
+            aut_list.append((phi, new_word))
+    return aut_list

free_groups_26/free_group.py

@@ -0,0 +1,49 @@
+from collections.abc import MutableSet
+
+from .letter import Symbol, Letter
+from sortedcontainers import SortedSet
+
+
+class FreeGroup:
+
+    basis: MutableSet[Symbol]  #: Implemented using a SortedSet from sortedcontainers.
+    alphabet: MutableSet[Letter]
+    """
+    Also implemented using a SortedSet. Represented by :math:`X^{\\pm}`.
+
+    Automatically inferred from :py:attr:`basis`. For :math:`x \\in X`, :math:`x, x^{-1} \\in X^{\\pm}`.
+    """
+    rank: int  #: Automatically inferred from :py:attr:`basis`.
+
+    def __init__(self, basis: MutableSet[Symbol]) -> None:
+        """
+        This class represents a Free Group.
+
+        :param basis: The basis of the free group.
+        :type basis: set[Symbol]
+        """
+        self.basis = SortedSet(basis)
+        self.rank = len(basis)
+        temp_alphabet: MutableSet[Letter] = SortedSet()
+        for sym in basis:
+            temp_alphabet.add(Letter(sym, 1))
+            temp_alphabet.add(Letter(sym, -1))
+        self.alphabet = temp_alphabet
+
+    def _get_hash_dict(self) -> dict[int, Letter]:
+        hash_dict: dict[int, Letter] = dict()
+        for elem in self.alphabet:
+            hash_dict[hash(elem)] = elem
+        return hash_dict
+
+
+def get_free_group(rank: int) -> FreeGroup:
+    """
+    Generates a free group of the given rank. The basis of the free group will be the symbols from the English Alphabet from ``a`` (in unicode order).
+
+    :param int rank: The rank of the free group.
+    """
+    basisSet: MutableSet[Symbol] = SortedSet()
+    for i in range(97, 97 + rank):
+        basisSet.add(chr(i))
+    return FreeGroup(basisSet)

free_groups_26/letter.py

@@ -0,0 +1,146 @@
+"""
+This submodule deals with Letters. Exposes the Letter class and a method to read letters, namely :py:func:`letter_from_str`.
+"""
+
+from __future__ import annotations
+from typing import override
+
+from dataclasses import dataclass
+from functools import total_ordering
+
+__all__ = [
+    "Letter",
+    "letter_from_str",
+    "letter_from_str_a",
+    "letter_from_str_b",
+]
+
+type Symbol = str
+type Exponent = int
+
+
+@total_ordering
+@dataclass(frozen=True, slots=True)
+class Letter:
+    """
+    This class represents a letter. Implements a total ordering, ``__eq__`` and ``__hash__``.
+
+    .. note::
+
+        Public access of both instance variables (:py:attr:`sym` and :py:attr:`exp`) is encouraged.
+
+    :param symbol: The symbol of the letter. All strings are valid symbols.
+    :type symbol: :py:type:`Symbol`
+    :param exponent: The exponent of the letter.
+    :type exponent: :py:type:`Exponent`
+
+    >>> Letter("a", 1)
+    a
+    >>> Letter("x", 3)
+    x^3
+    """
+
+    sym: Symbol  #:
+    exp: Exponent  #:
+
+    @override
+    def __repr__(self) -> str:
+        if self.exp == 1:
+            return self.sym
+        else:
+            return self.sym + "^" + str(self.exp)
+
+    @override
+    def __str__(self) -> str:
+        return abs(self.exp) * (self.sym if self.exp >= 0 else self.sym.upper())
+
+    def __lt__(self, other: object) -> bool:
+        """
+        Checks if ``self < other``. The following ordering is followed:
+
+        .. math::
+
+            a < a^2 < \\ldots < a^{-2} < a^{-1} < b < \\ldots
+
+        :param object other: The object to compare against.
+
+        Returns ``NotImplemented`` if ``other`` is not a :py:type:`Letter`.
+
+        """
+        if not isinstance(other, Letter):
+            return NotImplemented
+        else:
+            if self.sym < other.sym:
+                return True
+            else:
+                if self.exp * other.exp > 0:
+                    return self.exp < other.exp
+                else:
+                    return self.exp > 0
+
+    def is_inverse(self) -> bool:
+        """
+        Returns ``True`` if the exponent is less than 0.
+        """
+        return self.exp < 0
+
+    def inv(self) -> Letter:
+        """
+        Returns the inverse.
+        """
+        return Letter(self.sym, -self.exp)
+
+    def get_base(self) -> Letter:
+        """
+        Returns the base of the letter, which is defined as :math:`a^{\\frac{b}{|b|}}` for :math:`a^b`.
+        """
+        return Letter(self.sym, (self.exp > 0) - (self.exp < 0))
+
+
+def letter_from_str_b(raw: str) -> Letter:
+    """
+    Do not use unless you're sure what you're doing! Use :py:func:`letter_from_str` instead. \n
+    Returns a letter from a string of the format ``{sym}^{exp}``.
+
+    >>> letter_from_str_b("b^32")
+    b³²
+
+    """
+    splits = raw.split("^")
+    if len(splits) == 1:
+        return Letter(splits[0], 1)
+    return Letter(splits[0], int(splits[1]))
+
+
+def letter_from_str_a(char: str) -> Letter:
+    """
+    Do not use unless you're sure what you're doing! Use :py:func:`letter_from_str` instead. \n
+    Another way to generate a letter from a string. This function works exclusively on the English Alphabet, where it considers uppercase letters the inverse of lowercase letters.
+
+    >>> letter_from_str_a("a")
+    a
+    >>> letter_from_str_a("A")
+    a^-1
+
+    """
+    if len(char) > 1:
+        raise ValueError("Expected single character. Found {char}")
+    return Letter(
+        char.lower(),
+        1 if char.islower() else -1,
+    )
+
+
+def letter_from_str(char: str) -> Letter:
+    """
+    Use of this function is always recommended. Intelligently chooses between the two types of conversion.
+
+    >>> letter_from_str("b^32")
+    b^32
+    >>> letter_from_str("a")
+    a
+    >>> letter_from_str("A")
+    a^-1
+
+    """
+    return letter_from_str_b(char) if "^" in char else letter_from_str_a(char)

free_groups_26/log.py

@@ -0,0 +1,44 @@
+from typing import override
+
+from free_groups_26.morphism import Morphism
+from free_groups_26.word import Word
+
+type Log = list[LogItem]
+
+
+class LogItem:
+    """
+    Initializing this class manually is never recommended. Use :py:func:`new_log` to generate a :py:type:`Log` to pass where it is required.
+    Manual access of the instance variables is encouraged, however.
+    """
+
+    word: Word
+    """
+    The current word in the log.
+    """
+    morphism: Morphism
+    """
+    The morphism that led to the current word.
+    """
+
+    def __init__(self, word: Word, morphism: Morphism) -> None:
+        self.word = word
+        self.morphism = morphism
+
+    @override
+    def __repr__(self) -> str:
+        return str(self.word) + " : " + str(self.morphism.morphism_map)
+
+
+def new_log() -> Log:
+    """
+    Generates a new :py:type:`Log`. Recommended over using ``[]`` for readability.
+    """
+    return []
+
+
+def display_log(log: Log) -> None:
+    """
+    Prints out a :py:type:`Log` in a human readable fashion.
+    """
+    print("\n".join([str(log_item) for log_item in log]))

free_groups_26/minimize_bruteforce.py

@@ -0,0 +1,88 @@
+from collections.abc import Iterable
+
+from free_groups_26.log import Log, LogItem
+from .morphism import Morphism
+from .whitehead_automorphism import (
+    generate_all_t2_whitehead_automorphisms,
+    generate_t2_wh_aut_lazy,
+)
+from .word import Word
+
+
+def minimize_once_bruteforce(
+    word: Word, morphism_list: Iterable[Morphism], /, log: Log | None = None
+) -> tuple[Word, bool]:
+    """
+    Minimizes a word once, if possible.
+
+    :param word: The word to be minimized.
+    :param morphism_list: The list of all morphisms to try while minimizing the word.
+    :param log: (*keyword argument only*) Optional argument. The new word and the morphism used will be appended.
+    :return: Returns a tuple of (:py:class:`Word`, ``bool``). The second element specifies whether the word was reduced.
+
+    """
+    has_log: bool = log is not None
+    current_length = word.length
+    for morphism in morphism_list:
+        new_word = morphism.map(word)
+        if new_word.length < current_length:
+            if has_log:
+                log.append(LogItem(new_word, morphism))
+            return (new_word, True)
+    return (word, False)
+
+
+def minimize_once_bruteforce_lazy(
+    word: Word,
+    morphism_list: Iterable[Morphism] | None = None,
+    log: Log | None = None,
+) -> tuple[Word, bool]:
+    """
+    Similar to :py:func:`minimize_once_bruteforce`, but lazy evaluated. This is almost always recommended.
+
+    :param morphism_list: Passing a Morphism List has no effect.
+    """
+    has_log: bool = log is not None
+    for morphism in generate_t2_wh_aut_lazy(word.infer_free_group()):
+        new_word = morphism(word)
+        if new_word.length < word.length:
+            if has_log:
+                log.append(LogItem(new_word, morphism))
+            return (new_word, True)
+    return (word, False)
+
+
+def minimize_bruteforce(
+    word: Word,
+    lazy: bool = True,
+    morphism_list: Iterable[Morphism] | None = None,
+    /,
+    log: Log | None = None,
+) -> Word:
+    """
+    Returns the minimized form of the word, which might be the same word.
+
+    :param lazy: (Recommended) Enables lazy evaluation of the automorphisms. If this is on, passing a ``morphism_list`` has no effect.
+    :param morphism_list: If an iterable of morphisms is not provided, :py:func:`generate_all_t2_whitehead_automorphisms` is used to generate all possible Whitehead automorphisms for the given word. It is recommended that the list is generated and passed manually if working with multiple words from the same free group.
+    :param log: *(keyword argument only)* All mimization operations are appended to the log, if passed.
+
+    >>> log = new_log()
+    >>> minimize_bruteforce(rd("a b^2 c"), log=log)
+    c
+    >>> display_log(log)
+    abc : SortedDict({'a': ab⁻¹})
+    bc : SortedDict({'b': a⁻¹b})
+    c : SortedDict({'c': b⁻¹c})
+
+    """
+    if morphism_list is None and not lazy:
+        morphism_list = generate_all_t2_whitehead_automorphisms(word.infer_free_group())
+    new_word = word
+    minimize_function = (
+        minimize_once_bruteforce_lazy if lazy else minimize_once_bruteforce
+    )
+    while True:
+        new_word, reduced_in_cycle = minimize_function(new_word, morphism_list, log=log)
+        if not reduced_in_cycle:
+            break
+    return new_word

free_groups_26/morphism.py

@@ -0,0 +1,58 @@
+from typing import override, Any
+from sortedcontainers import SortedDict
+from .letter import Letter, Symbol
+from .word import Word
+
+
+class Morphism:
+    morphism_map: dict[Symbol, Word]
+    """
+    Implemented using a SortedDict from sortedcontainers.
+    """
+
+    def __init__(self, map: SortedDict | dict[Symbol, Word]):
+        """
+        This class represents a morphism.
+
+        :param map: The mapping of the morphism.
+        :type map: sortedcontainers.SortedDict or dict[Symbol, Word]
+
+        If a python dictionary is passed, it is automatically converted into a SortedDict. The SortedDict must be a mapping of :py:type:`Symbol` s to :py:class:`Word` s.
+        """
+        self.morphism_map = SortedDict(map)
+
+    @override
+    def __eq__(self, value: object, /) -> bool:
+        if not isinstance(value, Morphism):
+            return NotImplemented
+        else:
+            return self.morphism_map == value.morphism_map
+
+    def map(self, word: Word, reduce_cyclic: bool = False) -> Word:
+        """
+        Applies the morphism to a given word. If a symbol in the word has a map in :py:attr:`morphism_map`, then the corresponding mapping takes place, otherwise, the symbol is mapped to itself.
+
+        >>> d = SortedDict({'a' : wfs("a b^-1")})
+        >>> phi = Morphism(d)
+        >>> w = wfs("a^2 b^3")
+        >>> phi.map(w)
+        ab⁻¹ab²
+
+        """
+        newWord: list[Letter] = []
+        for letter in word.word:
+            if letter.sym not in self.morphism_map:
+                newWord.append(letter)
+            else:
+                newWord.extend((self.morphism_map[letter.sym] ** letter.exp).word)
+        return Word(newWord, reduce_cyclic)
+
+    def __call__(self, word: Word, *args: Any, **kwds: Any) -> Word:
+        """
+        Morphisms can be applied to words by directly calling them. (Aliased to :py:meth:`map`.)
+
+        >>> phi(w)
+        ab⁻¹ab²
+
+        """
+        return self.map(word)

free_groups_26/whitehead_automorphism.py

@@ -0,0 +1,92 @@
+from collections.abc import Iterable, Generator
+from itertools import chain, combinations
+from typing import Any
+
+from sortedcontainers import SortedDict, SortedSet
+
+from .free_group import FreeGroup
+from .letter import Letter, Symbol
+from .morphism import Morphism
+from .word import Word
+
+
+def _powerset(iterable):
+    s = list(iterable)
+    return chain.from_iterable(combinations(s, r) for r in range(len(s) + 1))
+
+
+def generate_whitehead_automorphism_t2(x: Letter, A: Iterable[Letter]) -> Morphism:
+    """
+    This function generates a Type 2 Whitehead Automorphism, using the following piecewise definition. (Credit: Virning, 1988)
+
+    .. math::
+
+        (A, x) y = \\begin{cases} 
+            yx & \\text{if } y \\in A, \\bar{y} \\notin A, y \\notin \\{x, \\bar{x}\\} \\\\ 
+            \\bar{x} y & \\text{if } y \\notin A, \\bar{y} \\in A, y \\notin \\{x, \\bar{x}\\} \\\\ 
+            \\bar{x} yx & \\text{if } y, \\bar{y} \\in A \\\\ 
+            y & \\text{otherwise} 
+        \\end{cases}
+
+    :param x: Corresponds to :math:`x` in the definition.
+    :param A: Corresponds to :math:`A` in the definition.
+
+    Instead of iterating through all the symbols in a free group, this function only goes through the symbols in ``A`` as the rest get mapped to themselves.
+
+    >>> wh = generate_whitehead_automorphism_t2(lfs("b"), {lfs("a"), lfs("a^-1"), lfs("b"), lfs("c^-1")})
+    >>> print(wh.morphism_map)
+    SortedDict({'a': b⁻¹ab, 'c': b⁻¹c})
+    >>> print(wh.map(wfsa("bac")))
+    ac
+
+    """
+
+    phi_map: dict[Symbol, Word] = SortedDict()
+
+    for ysym in SortedSet([k.sym for k in A]):
+        y = Letter(ysym, 1)
+
+        if y not in [x, x.inv()]:
+            if y in A and y.inv() in A:
+                phi_map[ysym] = Word((x.inv(), y, x))
+            elif y in A:
+                phi_map[ysym] = Word((y, x))
+            else:
+                phi_map[ysym] = Word((x.inv(), y))
+
+    return Morphism(phi_map)
+
+
+def generate_all_t2_whitehead_automorphisms(
+    inp: FreeGroup | set[Symbol],
+) -> list[Morphism]:
+    """
+    This function generates all Type 2 Whitehead Automorphisms for a given set of symbols. This function has a time and space complexity of :math:`O(4^n)`.
+    """
+    L_n = inp.alphabet if isinstance(inp, FreeGroup) else FreeGroup(inp).alphabet
+    morphism_list: list[Morphism] = []
+    for A in _powerset(L_n):
+        for x in A:
+            if x.inv() in A:
+                continue
+            phi = generate_whitehead_automorphism_t2(x, A)
+            if phi.morphism_map != {}:
+                morphism_list.append(phi)
+    return morphism_list
+
+
+def generate_t2_wh_aut_lazy(
+    inp: FreeGroup | set[Symbol],
+) -> Generator[Morphism, Any, None]:
+    """
+    Lazily generates all the Type 2 Whitehead Automorphisms for the given set of symbols / :py:class:`FreeGroup`.
+    Similar to :py:func:`generate_all_t2_whitehead_automorphisms`, but recommended for more efficient memory usage.
+    """
+    L_n = inp.alphabet if isinstance(inp, FreeGroup) else FreeGroup(inp).alphabet
+    for A in _powerset(L_n):
+        for x in A:
+            if x.inv() in A:
+                continue
+            phi = generate_whitehead_automorphism_t2(x, A)
+            if phi.morphism_map != {}:
+                yield phi

free_groups_26/whitehead_graph.py

@@ -0,0 +1,56 @@
+import networkx as nx
+import matplotlib.pyplot as plt
+
+from networkx import Graph
+from .letter import Letter
+from .word import Word
+
+type WhiteheadGraph = Graph[Letter]
+
+
+def generate_whg(word: Word) -> WhiteheadGraph:
+    """
+    Generates a Whitehead Graph for the given word.
+    """
+    whg: WhiteheadGraph = Graph()
+    cyclic = word.word + (word.word[0],)
+
+    for i in range(len(cyclic) - 1):
+        curr = cyclic[i].get_base()
+        next = cyclic[i + 1].get_base()
+
+        w_add = abs(cyclic[i].exp) - 1
+        if w_add != 0:
+            change_whg_edge_or_weight(whg, curr, curr.inv(), w_add)
+        change_whg_edge_or_weight(whg, curr, next.inv())
+
+    return whg
+
+
+def change_whg_edge_or_weight(
+    whg: WhiteheadGraph, v1: Letter, v2: Letter, weight: int = 1
+) -> None:
+    """
+    Changes the edge weights for an edge if it exists, otherwise adds the given edge to the graph.
+    """
+    try:
+        whg[v1][v2]["weight"] += weight
+    except KeyError:
+        _ = whg.add_edge(v1, v2, weight=weight)
+
+
+def draw_graph(G: WhiteheadGraph) -> None:
+    """
+    Uses matplotlib to draw the given Whitehead Graph.
+    """
+    pos = nx.spring_layout(G)
+    _ = nx.draw_networkx_nodes(G, pos, node_size=700)
+    _ = nx.draw_networkx_labels(G, pos, font_size=20)
+    _ = nx.draw_networkx_edges(G, pos, edgelist=G.edges, width=1)
+    edge_labels: dict[tuple[Letter, Letter], int] = nx.get_edge_attributes(G, "weight")
+    _ = nx.draw_networkx_edge_labels(G, pos, edge_labels)
+    ax = plt.gca()
+    _ = ax.margins(0.08)
+    plt.axis("off")
+    plt.tight_layout()
+    plt.show()

free_groups_26/whitehead_minimization.py

@@ -0,0 +1,120 @@
+from networkx import minimum_cut, NetworkXError
+from networkx.algorithms.flow import edmonds_karp
+from sortedcontainers import SortedDict
+
+from free_groups_26.log import Log, LogItem
+
+from .free_group import FreeGroup, get_free_group
+from .letter import Letter, Symbol
+from .morphism import Morphism
+from .word import Word
+from .whitehead_automorphism import generate_whitehead_automorphism_t2
+from .whitehead_graph import WhiteheadGraph, generate_whg
+
+
+def minimize_whitehead_once(
+    word: Word, /, fg: FreeGroup | None = None, log: Log | None = None
+) -> Word | None:
+    """
+    Performs Whitehead Minimization once.
+
+    :param word: The word to be minimized.
+    :param fg: An optional free group can be passed if you wish to avoid the overhead of inferring the free group from the word. (Recommended for large words.)
+    :type fg: :py:class:`FreeGroup` or ``None``
+    :param log: An optional log. If passed, all morphisms tried will be appended as strings, with some other information.
+    :type log: :py:type:`Log` or ``None``.
+    :return: If minimal, returns ``None``, otherwise returns the once-minimized word.
+
+    **Current Implementation**: Iterate through the alphabet of the free group (inferred or given), if the max flow of the current alphabet to its inverse is less than its degree, try creating and applying a whitehead
+    automorphism with :py:func:`generate_whitehead_automorphism_t2`. If the length of the word is less than the given word (not guaranteed by a min cut), return it, otherwise continue iterating.
+
+    The min cut is computed using Edmonds Karp.
+
+    >>> log = new_log()
+    >>> minimize_whitehead_once(rd("a b^2 c"), log=log)
+    b²c
+    >>> display_log(log)
+    b²c : SortedDict({'b': a⁻¹ba, 'c': a⁻¹c})
+
+    """
+    graph: WhiteheadGraph = generate_whg(word)
+    if fg is None:
+        fg = word.infer_free_group()
+
+    for letter in fg.alphabet:
+        try:
+            value, partitions = minimum_cut(
+                graph, letter, letter.inv(), capacity="weight", flow_func=edmonds_karp
+            )
+            partitions: tuple[set[Letter], set[Letter]]
+            value: int
+        except NetworkXError:
+            continue
+        if value < graph.degree(letter, weight="weight"):
+            phi = generate_whitehead_automorphism_t2(letter, partitions[0])
+            new_word = phi.map(word, True)
+            if log is not None:
+                log.append(LogItem(new_word, phi))
+            if new_word.length < word.length:
+                return new_word
+    else:
+        return None
+
+
+def minimize_whitehead(
+    word: Word, /, fg: FreeGroup | None = None, log: Log | None = None
+) -> Word:
+    """
+    Whitehead Minimizes a word.
+
+    :param word: The word to be minimized.
+    :param fg: The optional free group. If not passed, it is inferred from the word.
+    :type fg: :py:class:`FreeGroup` or ``None``
+    :param log: All operations performed are appended to the log, if passed.
+    :type log: :py:type:`Log` or ``None``.
+
+    **Current Implementation**: Keep trying :py:func:`minimize_whitehead_once` on the word, reassigning the returns. If it returns a ``None``, then this function returns the minimized word.
+
+    >>> minimize_whitehead(wfs("c^-3 b^-1 a^2"))
+    c⁻¹
+
+    """
+    fg = fg if fg is not None else word.infer_free_group()
+    new_word = word
+    while True:
+        minimized = minimize_whitehead_once(new_word, fg=fg, log=log)
+        if minimized is None:
+            break
+        new_word = minimized
+    return new_word
+
+
+def is_minimal(word: Word, fg: FreeGroup | None = None) -> bool:
+    """
+    :return: Whether the word is already whitehead minimal.
+    """
+    return minimize_whitehead(word, fg=fg) == word
+
+
+def type_1_minimize(word: Word) -> tuple[Word, Morphism]:
+    """
+    Finds a Type 1 Whitehead Automorphism that makes the word lexicographically minimal.
+
+    >>> w = rd("k m^-1 y^-2 m y")
+    >>> nw, m = type_1_minimize(w)
+    >>> nw, m.morphism_map
+    (abc²b⁻¹c⁻¹, SortedDict({'k': a, 'm': b⁻¹, 'y': c⁻¹}))
+
+    """
+    canonical_free_group = get_free_group(word.infer_free_group().rank)
+    generator = iter(canonical_free_group.basis)
+    word_iter = iter(word)
+    phi_map: dict[Symbol, Word] = SortedDict()
+    while len(phi_map) < canonical_free_group.rank:
+        curr_letter = next(word_iter)
+        if curr_letter.sym not in phi_map:
+            phi_map[curr_letter.sym] = Word(
+                (Letter(next(generator), curr_letter.get_base().exp),)
+            )
+    phi = Morphism(phi_map)
+    return (phi(word), phi)

free_groups_26/word/__init__.py

@@ -0,0 +1,21 @@
+"""
+This module defines the Word Class and functions on words.
+"""
+
+from .defn import Word
+from .functions import (
+    generate_random_word,
+    word_from_str_a,
+    word_from_str_b,
+    word_from_str,
+    read,
+)
+
+__all__ = [
+    "Word",
+    "generate_random_word",
+    "word_from_str_a",
+    "word_from_str_b",
+    "word_from_str",
+    "read",
+]

free_groups_26/word/defn.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+from collections.abc import Iterable, MutableSet, Sequence
+from symtable import Symbol
+from typing import overload, override
+
+from sortedcontainers import SortedSet
+
+from free_groups_26.free_group import FreeGroup
+from free_groups_26.letter import Exponent, Letter
+
+__all__ = ["Word"]
+
+
+class Word(Sequence[Letter]):
+    word: tuple[Letter, ...]
+    length: int
+
+    def __init__(self, word: Iterable[Letter], cyclically_reduce: bool = False) -> None:
+        """
+        This class represents a word.
+
+        :param word: Any :py:type:`Iterable` containing :py:class:`Letter` s is accepted.
+        """
+        super().__init__()
+        m_word: list[Letter] = []
+        for letter in word:
+            reduce_word_helper(m_word, letter)
+        if cyclically_reduce:
+            reduce_cyclic(m_word)
+        self.word = tuple(m_word)
+        self.length = sum(abs(x.exp) for x in self.word)
+
+    @override
+    def __len__(self) -> int:
+        return self.length
+
+    @overload
+    def __getitem__(self, index: int) -> Letter: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> Word: ...
+
+    @override
+    def __getitem__(self, index: int | slice) -> Letter | Word:
+        if isinstance(index, int):
+            return self.word[index]
+        else:
+            return Word(self.word[index])
+
+    def __mul__(self, other: object) -> Word:
+        if isinstance(other, Word):
+            return Word(self.word + other.word)
+        elif isinstance(other, Letter):
+            return Word(self.word + (other,))
+        else:
+            return NotImplemented
+
+    def __rmul__(self, other: object) -> Word:
+        if isinstance(other, Word):
+            return other * self
+        elif isinstance(other, Letter):
+            return Word((other,) + self.word)
+        else:
+            return NotImplemented
+
+    def inv(self) -> Word:
+        return Word(
+            Letter(element.sym, -1 * element.exp) for element in self.word[::-1]
+        )
+
+    @override
+    def __eq__(self, value: object, /) -> bool:
+        return isinstance(value, Word) and self.word == value.word
+
+    @override
+    def __hash__(self) -> int:
+        return hash(self.word)
+
+    def __pow__(self, exp: Exponent) -> Word:
+        """
+        Words can be exponentiated.
+
+        >>> read("a^3 b^2 c^-3") ** 4
+        a³b²c⁻³a³b²c⁻³a³b²c⁻³a³b²c⁻³
+        >>> read("a^3 b^-2") ** -2
+        b²a⁻³b²a⁻³
+
+        """
+        if exp < 0:
+            return (self**-exp).inv()
+        elif exp == 0:
+            return Word(())
+        else:
+            newWord: list[Letter] = []
+            for _ in range(exp):
+                newWord.extend(self.word)
+            return Word(newWord)
+
+    def is_cyclically_reduced(self) -> bool:
+        """
+        :return: whether the word is cyclically reduced. Assumes that the given word is reduced linearly.
+        """
+        if len(self.word) <= 1:
+            return True
+        return self.word[0].sym != self.word[-1].sym
+
+    def infer_free_group(self) -> FreeGroup:
+        """
+        Infers the :py:class:`FreeGroup` ``self`` is an element of.
+
+        >>> wfs("a^2 b k^3 b^-2").infer_free_group().basis
+        SortedSet(['a', 'b', 'k'])
+
+        """
+        basis: MutableSet[Symbol] = SortedSet()
+        for letter in self.word:
+            if letter.sym not in basis:
+                basis.add(letter.sym)  # pyright: ignore[reportUnknownMemberType]
+        return FreeGroup(basis)
+
+    @override
+    def __repr__(self) -> str:
+        """
+        Words are represented with unicode characters by default.
+        """
+        if self.length == 0:
+            return "ε"
+        return " ".join([repr(elem) for elem in self.word])
+
+    @override
+    def __str__(self) -> str:
+        """
+        Words are represented with unicode characters by default.
+        """
+        if self.length == 0:
+            return "ε"
+        return "".join([str(elem) for elem in self.word])
+
+
+def reduce_word_helper(stack: list[Letter], letter: Letter) -> None:
+    if letter.exp == 0:
+        return
+    elif len(stack) == 0:
+        stack.append(letter)
+    elif stack[-1].sym == letter.sym:
+        reduce_word_helper(stack, Letter(letter.sym, stack.pop().exp + letter.exp))
+    else:
+        stack.append(letter)
+
+
+def reduce_cyclic(stack: list[Letter]) -> None:
+    while len(stack) > 1 and stack[0].sym == stack[-1].sym:
+        reduce_word_helper(stack, stack.pop(0))
+
+
+class ReducedWord(Word):
+    def __init__(self, word: Iterable[Letter], cyclic: bool = False) -> None:
+        m_word: list[Letter] = []
+        for letter in self.word:
+            reduce_word_helper(m_word, letter)
+        if cyclic:
+            reduce_cyclic(m_word)
+        super().__init__(m_word)

free_groups_26/word/functions.py

@@ -0,0 +1,84 @@
+from free_groups_26.free_group import FreeGroup
+from free_groups_26.letter import Letter, Symbol, letter_from_str_a, letter_from_str_b
+from .defn import Word, reduce_cyclic
+import random
+
+__all__ = ["generate_random_word"]
+
+
+def generate_random_word(group: FreeGroup, length: int, variation: int) -> Word:
+    """
+    Generates a cyclically reduced pseudo-random word from the given free group.
+
+    :param group: The free group of the generated word.
+    :type group: :py:class:`FreeGroup`
+    :param int length: The length of the generated word will be roughly around ``length`` :math:`\\pm` ``variation``.
+    :param int variation: The absolute value of the highest power of a letter in the free group. For example, if ``variation = 4``, the exponents of
+                          the letters in the word are guaranteed to be between 4 and -4.
+    """
+    newWord: list[Letter] = []
+    prevSym: Symbol = ""
+    count = 0
+    while count <= length:
+        sym: Symbol = tuple(group.basis)[random.randint(0, group.rank - 1)]
+        if sym == prevSym:
+            continue
+        prevSym = sym
+        expo = 0
+        while expo == 0:
+            expo = random.randint(-variation, variation)
+        newWord.append(Letter(sym, expo))
+        count += abs(expo)
+    reduce_cyclic(newWord)
+    return Word(newWord)
+
+
+def word_from_str_b(raw: str) -> Word:
+    """
+    Generates a word from a string of the format ``"{sym}^{exp} {letter} ...``. This is consistent with :py:func:`letter_from_str_b`.
+    Use of :py:func:`read` is recommended.
+
+    :param str raw: The string to be parsed.
+
+    >>> word_from_str("a^2 b^3")
+    a^2 b^3
+
+    """
+    return Word(letter_from_str_b(i) for i in raw.split(" "))
+
+
+def word_from_str_a(raw: str) -> Word:
+    """
+    Another way to generate a :py:type:`word` from a string, when your letters are exclusively from the English alphabet.
+    Uppercase letters are considered the inverses of lowercase letters. See below for examples.
+    Use of :py:func:`read` is recommended.
+
+    See :py:func:`letter_from_str_alphabet`.
+
+    :param str raw: The string to be parsed.
+    :return: The returned word is reduced by default.
+
+    >>> str(word_from_str_alphabet("aaaAbBCCccccc"))
+    aaaAbBCCccccc
+    >>> str(word_from_str_alphabet("AAAABBBBHHHHMMMkk"))
+    AAAABBBBHHHHMMMkk
+
+    """
+    return Word(map(letter_from_str_a, raw))
+
+
+def word_from_str(inp: str) -> Word:
+    """
+    Parses a word from a string. Guesses the correct function to use from :py:func:`word_from_str_a` and :py:func:`word_from_str_b` based on whether there is a
+    caret ``^`` in the input. Recommended in most cases.
+    """
+    if "^" in inp:
+        return word_from_str_b(inp)
+    else:
+        return word_from_str_a(inp)
+
+
+read = word_from_str
+"""
+Alias to :py:func:`word_from_str`. Recommended when brevity is desired.
+"""

free_groups_26-1.2.0.dist-info/METADATA

@@ -0,0 +1,31 @@
+Metadata-Version: 2.5
+Name: free_groups_26
+Version: 1.2.0
+Summary: A Python Module for working with Free Groups
+Project-URL: Documentation, https://www.sudhirkrisna.com/free_groups_26/
+Project-URL: Repository, https://github.com/Sudhboi/free_groups_26
+Project-URL: Issues, https://github.com/Sudhboi/free_groups_26/issues
+Author-email: Sudhir Krisna <sudhcontent@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.13
+Requires-Dist: matplotlib>=3.10.8
+Requires-Dist: networkx>=3.6.1
+Requires-Dist: sortedcontainers>=2.4.0
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Description-Content-Type: text/markdown
+
+# free_groups_26
+
+### Install:
+```
+pip install free-groups-26
+```
+
+Documentation can be found at the official website - [free_groups_26](https://www.sudhirkrisna.com/free_groups_26/index.html)

free_groups_26-1.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+free_groups_26/__init__.py,sha256=RZxnzzIuLS-86qCAsjyTyhgzpruJApxrP29Td6FTH8A,1008
+free_groups_26/aut_orbit_bruteforce.py,sha256=vaBjMZClOgAEIjqT1su0iQN-um4mg1ZOwYkJedkRbmE,665
+free_groups_26/free_group.py,sha256=l1RzAwPSxGWgYyxmQVHcy3-AwyNZVYeIWaWMNifW1n0,1612
+free_groups_26/letter.py,sha256=PRPLmyI-9WSzNgu3GPJDxR6kMDSd-c8ZILjhnfFlHWE,3845
+free_groups_26/log.py,sha256=oVphsZvyZCRrfmPzQ843dq81evxScKA7NXjU0ydZSYM,1080
+free_groups_26/minimize_bruteforce.py,sha256=xC1TxmwcP4ClVnolt13HkrWffVHi5XEjC7lcNjAkDxk,3272
+free_groups_26/morphism.py,sha256=RYF4QhW2UTeX8ZbfUkYl3F37UugDW073eJNMzt9oKfM,1947
+free_groups_26/whitehead_automorphism.py,sha256=LV01dMiHpFMJhTolE8ychXUsjhUp9iaG7YxQnhKZVO0,3254
+free_groups_26/whitehead_graph.py,sha256=F91De94GMDXGLB_yozFgLWcg8ZtedZoARVu2XmC94gY,1590
+free_groups_26/whitehead_minimization.py,sha256=cAph5nU8cYLBMUWitWCj96oAQ6U52H0reKLEleQ1Ujk,4568
+free_groups_26/word/__init__.py,sha256=qPI4Oyjd7fg9yw8eh99IRfYqtjnS4BUtXIuwzrOWP8I,349
+free_groups_26/word/defn.py,sha256=-FDaL9VTkrTR7dFsq2SlMT8aw0dWElhhWIXs8irozIU,4781
+free_groups_26/word/functions.py,sha256=r7lVTMLcQBXJBwQM6OROXlqQfPRT5N7gN9JWiE358N4,2844
+free_groups_26-1.2.0.dist-info/METADATA,sha256=nWTQw4YTPbnwqwJP4SpDCJHW1jwYRREq3utBERci8lc,1040
+free_groups_26-1.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+free_groups_26-1.2.0.dist-info/licenses/LICENSE,sha256=zdv9z3A6yiSjuvbDlFwNK8AnGLTpNx2Rb5h64f6Lubo,1070
+free_groups_26-1.2.0.dist-info/RECORD,,

free_groups_26-1.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

free_groups_26-1.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sudhir Krisna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.