mathematicskit 0.2.0__tar.gz → 0.2.1__tar.gz

{mathematicskit-0.2.0 → mathematicskit-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mathematicskit
-Version: 0.2.0
+Version: 0.2.1
 Summary: Unified computational mathematics toolkit: numerical analysis, linear algebra, calculus, dynamical systems, optimization, probability, statistics, number theory, combinatorics, graph theory, abstract algebra, geometry, special functions, and fractals/chaos -- all hand-rolled from first principles.
 Author-email: Charles Poli <cpoli374@gmail.com>
 Maintainer-email: Charles Poli <cpoli374@gmail.com>

{mathematicskit-0.2.0 → mathematicskit-0.2.1}/mathematicskit/__init__.py

@@ -28,7 +28,7 @@ from mathematicskit import (
     statistics,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"
 
 __all__ = [
     "abstract_algebra",

mathematicskit-0.2.1/mathematicskit/abstract_algebra/__init__.py

@@ -0,0 +1,94 @@
+"""mathematicskit.abstract_algebra: group, ring, and field theory made computational.
+
+Every algorithm here is hand-rolled from its textbook definition --
+finite group/ring/field theory has no ``numpy``/``scipy`` equivalent.
+Cyclic, permutation, dihedral, and quaternion group implementations
+with Cayley table generation; group-property checks (order, identity,
+inverses, abelian, cyclicity); subgroup and coset enumeration for small
+groups; structure theory (normal subgroups and quotients, derived
+series and solvability, Sylow subgroups, composition series); group
+actions and Burnside orbit counting; homomorphisms and their kernels
+and images; Reed-Solomon codes over ``GF(p)``; finite
+field arithmetic (``GF(p)`` and ``GF(p^n)`` via irreducible polynomials
+over ``GF(p)``); and polynomial ring arithmetic (addition,
+multiplication, division with remainder, gcd) over :math:`\\mathbb{Z}`,
+:math:`\\mathbb{Q}`, and finite fields.
+"""
+
+from mathematicskit.abstract_algebra.core.base import (
+    CompositionSeriesResult,
+    FiniteGroup,
+    GroupPropertiesResult,
+    HomomorphismResult,
+    Polynomial,
+    SylowResult,
+)
+from mathematicskit.abstract_algebra.systems.actions import count_orbits, orbits
+from mathematicskit.abstract_algebra.systems.codes import rs_decode_erasures, rs_encode
+from mathematicskit.abstract_algebra.systems.finite_fields import GF, find_irreducible_polynomial, is_irreducible
+from mathematicskit.abstract_algebra.systems.groups import CyclicGroup, DihedralGroup, PermutationGroup, QuaternionGroup, group_properties
+from mathematicskit.abstract_algebra.systems.homomorphisms import analyze_homomorphism, homomorphism_image, homomorphism_kernel, is_homomorphism
+from mathematicskit.abstract_algebra.systems.polynomial_ring import poly_add, poly_divmod, poly_gcd, poly_mul, poly_sub
+from mathematicskit.abstract_algebra.systems.structure import (
+    QuotientGroup,
+    Subgroup,
+    commutator_subgroup,
+    composition_series,
+    derived_series,
+    elements_of_order,
+    generated_subgroup,
+    is_normal_subgroup,
+    is_solvable,
+    quotient_group,
+    sylow_subgroups,
+)
+from mathematicskit.abstract_algebra.systems.subgroups import all_subgroups, cyclic_subgroup, left_cosets
+from mathematicskit.abstract_algebra.utils.checks import is_cyclic
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "FiniteGroup",
+    "GroupPropertiesResult",
+    "Polynomial",
+    "CyclicGroup",
+    "PermutationGroup",
+    "group_properties",
+    "is_cyclic",
+    "cyclic_subgroup",
+    "all_subgroups",
+    "left_cosets",
+    "GF",
+    "is_irreducible",
+    "find_irreducible_polynomial",
+    "poly_add",
+    "poly_sub",
+    "poly_mul",
+    "poly_divmod",
+    "poly_gcd",
+    "SylowResult",
+    "CompositionSeriesResult",
+    "HomomorphismResult",
+    "DihedralGroup",
+    "QuaternionGroup",
+    "Subgroup",
+    "generated_subgroup",
+    "elements_of_order",
+    "is_normal_subgroup",
+    "QuotientGroup",
+    "quotient_group",
+    "commutator_subgroup",
+    "derived_series",
+    "is_solvable",
+    "sylow_subgroups",
+    "composition_series",
+    "orbits",
+    "count_orbits",
+    "is_homomorphism",
+    "homomorphism_kernel",
+    "homomorphism_image",
+    "analyze_homomorphism",
+    "rs_encode",
+    "rs_decode_erasures",
+]

{mathematicskit-0.2.0 → mathematicskit-0.2.1}/mathematicskit/abstract_algebra/core/base.py

@@ -17,7 +17,7 @@ from typing import Optional
 
 import numpy as np
 
-__all__ = ["FiniteGroup", "GroupPropertiesResult", "Polynomial"]
+__all__ = ["FiniteGroup", "GroupPropertiesResult", "SylowResult", "CompositionSeriesResult", "HomomorphismResult", "Polynomial"]
 
 
 class FiniteGroup(ABC):
@@ -124,6 +124,41 @@ class GroupPropertiesResult:
     """dict: ``{element: order}`` for every element."""
 
 
+@dataclass
+class SylowResult:
+    """Container for the Sylow :math:`p`-subgroups of a finite group."""
+
+    p: int
+    sylow_order: int
+    """int: :math:`p^k`, the largest power of ``p`` dividing :math:`|G|`."""
+    subgroups: list
+    """list of list: Every Sylow :math:`p`-subgroup, each as a list of elements."""
+
+    @property
+    def count(self) -> int:
+        """int: :math:`n_p`, the number of Sylow :math:`p`-subgroups."""
+        return len(self.subgroups)
+
+
+@dataclass
+class CompositionSeriesResult:
+    """Container for a composition series :math:`G = G_0 > G_1 > \\dots > G_m = \\{e\\}`."""
+
+    series: list
+    """list of list: The subgroups :math:`G_0, \\dots, G_m`, largest first."""
+    factor_orders: list
+    """list of int: The orders :math:`|G_i / G_{i+1}|` of the composition factors."""
+
+
+@dataclass
+class HomomorphismResult:
+    """Container for a group homomorphism's kernel and image."""
+
+    kernel: list
+    image: list
+    is_homomorphism: bool
+
+
 class Polynomial:
     r"""A polynomial with coefficients over :math:`\mathbb{Q}` (``modulus=None``,
     stored as exact :class:`fractions.Fraction`) or :math:`\mathrm{GF}(p)`
@@ -189,19 +224,29 @@ class Polynomial:
             return -1
         return len(self.coeffs) - 1
 
+    def _check_same_field(self, other: Polynomial) -> None:
+        """Reject arithmetic between polynomials over different coefficient fields."""
+        if not isinstance(other, Polynomial):
+            raise TypeError(f"expected a Polynomial, got {type(other).__name__}")
+        if self.modulus != other.modulus:
+            raise ValueError(f"cannot combine polynomials over different fields (modulus {self.modulus} vs {other.modulus})")
+
     def _pad(self, n: int) -> list:
         zero = Fraction(0) if self.modulus is None else 0
         return self.coeffs + [zero] * (n - len(self.coeffs))
 
     def __add__(self, other: Polynomial) -> Polynomial:
+        self._check_same_field(other)
         n = max(len(self.coeffs), len(other.coeffs))
         return self._wrap([self._reduce(a + b) for a, b in zip(self._pad(n), other._pad(n))])
 
     def __sub__(self, other: Polynomial) -> Polynomial:
+        self._check_same_field(other)
         n = max(len(self.coeffs), len(other.coeffs))
         return self._wrap([self._reduce(a - b) for a, b in zip(self._pad(n), other._pad(n))])
 
     def __mul__(self, other: Polynomial) -> Polynomial:
+        self._check_same_field(other)
         result = [Fraction(0) if self.modulus is None else 0] * (len(self.coeffs) + len(other.coeffs) - 1)
         for i, a in enumerate(self.coeffs):
             for j, b in enumerate(other.coeffs):
@@ -216,6 +261,7 @@ class Polynomial:
 
     def __divmod__(self, other: Polynomial):
         r"""Polynomial long division: ``self = quotient * other + remainder``, ``deg(remainder) < deg(other)``."""
+        self._check_same_field(other)
         if other.degree == -1:
             raise ZeroDivisionError("division by the zero polynomial")
         remainder = self._wrap(list(self.coeffs))

mathematicskit-0.2.1/mathematicskit/abstract_algebra/systems/__init__.py

@@ -0,0 +1,60 @@
+"""Concrete group, ring, and field algorithms."""
+
+from mathematicskit.abstract_algebra.systems.actions import count_orbits, orbits
+from mathematicskit.abstract_algebra.systems.codes import rs_decode_erasures, rs_encode
+from mathematicskit.abstract_algebra.systems.finite_fields import GF, find_irreducible_polynomial, is_irreducible
+from mathematicskit.abstract_algebra.systems.groups import CyclicGroup, DihedralGroup, PermutationGroup, QuaternionGroup, group_properties
+from mathematicskit.abstract_algebra.systems.homomorphisms import analyze_homomorphism, homomorphism_image, homomorphism_kernel, is_homomorphism
+from mathematicskit.abstract_algebra.systems.polynomial_ring import poly_add, poly_divmod, poly_gcd, poly_mul, poly_sub
+from mathematicskit.abstract_algebra.systems.structure import (
+    QuotientGroup,
+    Subgroup,
+    commutator_subgroup,
+    composition_series,
+    derived_series,
+    elements_of_order,
+    generated_subgroup,
+    is_normal_subgroup,
+    is_solvable,
+    quotient_group,
+    sylow_subgroups,
+)
+from mathematicskit.abstract_algebra.systems.subgroups import all_subgroups, cyclic_subgroup, left_cosets
+
+__all__ = [
+    "CyclicGroup",
+    "PermutationGroup",
+    "group_properties",
+    "cyclic_subgroup",
+    "all_subgroups",
+    "left_cosets",
+    "GF",
+    "is_irreducible",
+    "find_irreducible_polynomial",
+    "poly_add",
+    "poly_sub",
+    "poly_mul",
+    "poly_divmod",
+    "poly_gcd",
+    "DihedralGroup",
+    "QuaternionGroup",
+    "Subgroup",
+    "generated_subgroup",
+    "elements_of_order",
+    "is_normal_subgroup",
+    "QuotientGroup",
+    "quotient_group",
+    "commutator_subgroup",
+    "derived_series",
+    "is_solvable",
+    "sylow_subgroups",
+    "composition_series",
+    "orbits",
+    "count_orbits",
+    "is_homomorphism",
+    "homomorphism_kernel",
+    "homomorphism_image",
+    "analyze_homomorphism",
+    "rs_encode",
+    "rs_decode_erasures",
+]

mathematicskit-0.2.1/mathematicskit/abstract_algebra/systems/actions.py

@@ -0,0 +1,92 @@
+r"""Group actions on finite sets: orbits and Burnside's orbit-counting lemma.
+
+No numpy/scipy equivalent. See Dummit & Foote, *Abstract Algebra*, 3rd
+ed., Sec. 4.1 (group actions), and W. Burnside, *Theory of Groups of
+Finite Order* (Cambridge: Cambridge University Press, 1897), Sec. 145.
+"""
+
+from __future__ import annotations
+
+from fractions import Fraction
+from typing import Callable
+
+from mathematicskit.abstract_algebra.core.base import FiniteGroup
+
+__all__ = ["orbits", "count_orbits"]
+
+
+def orbits(group: FiniteGroup, points, action: Callable) -> list:
+    r"""The orbits of `group` acting on `points`, found by direct search.
+
+    Parameters
+    ----------
+    group : FiniteGroup
+    points : iterable
+        A finite set closed under the action.
+    action : callable
+        ``action(g, x)`` returns the image of point ``x`` under group element ``g``.
+
+    Returns
+    -------
+    list of list
+        Each orbit as a list of points.
+
+    Examples
+    --------
+    >>> from mathematicskit.abstract_algebra.systems.groups import CyclicGroup
+    >>> rotate = lambda g, word: word[g:] + word[:g]  # Z_3 rotating 3-letter words
+    >>> len(orbits(CyclicGroup(3), ["aab", "aba", "baa", "aaa"], rotate))
+    2
+    """
+    seen = set()
+    result = []
+    for x in points:
+        if x in seen:
+            continue
+        orbit = []
+        for g in group.elements:
+            y = action(g, x)
+            if y not in seen:
+                seen.add(y)
+                orbit.append(y)
+        result.append(orbit)
+    return result
+
+
+def count_orbits(group: FiniteGroup, points, action: Callable) -> int:
+    r"""The number of orbits, by Burnside's lemma: the average number of fixed points.
+
+    .. math::
+
+       |X/G| = \frac{1}{|G|} \sum_{g \in G} |\mathrm{Fix}(g)|
+
+    The formula was known to Augustin-Louis Cauchy (1845) and Ferdinand
+    Georg Frobenius (1887); William Burnside's 1897 book made it
+    standard. Counting fixed points is usually far easier than listing
+    orbits. See Dummit & Foote, *Abstract Algebra*, 3rd ed., Sec. 4.1.
+
+    Parameters
+    ----------
+    group : FiniteGroup
+    points : iterable
+    action : callable
+        ``action(g, x)`` returns the image of point ``x`` under ``g``.
+
+    Returns
+    -------
+    int
+
+    Examples
+    --------
+    >>> from itertools import product
+    >>> from mathematicskit.abstract_algebra.systems.groups import CyclicGroup
+    >>> necklaces = ["".join(w) for w in product("RB", repeat=4)]  # 2-colored 4-bead necklaces
+    >>> count_orbits(CyclicGroup(4), necklaces, lambda g, w: w[g:] + w[:g])
+    6
+    """
+    points = list(points)
+    total = sum(sum(1 for x in points if action(g, x) == x) for g in group.elements)
+    count = Fraction(total, group.order)
+    if count.denominator != 1:
+        raise ValueError("fixed-point average is not an integer; is `action` a genuine group action?")
+    return int(count)

mathematicskit-0.2.1/mathematicskit/abstract_algebra/systems/codes.py

@@ -0,0 +1,103 @@
+r"""Reed-Solomon codes over a prime field :math:`\mathrm{GF}(p)`, in their
+original evaluation form.
+
+A message of :math:`k` symbols is read as the coefficients of a
+polynomial of degree below :math:`k`; the codeword is that polynomial's
+values at :math:`n` distinct field elements. Any :math:`k` surviving
+values determine the polynomial by Lagrange interpolation, so the code
+recovers from up to :math:`n-k` erasures. No numpy/scipy equivalent
+(exact modular arithmetic). See I. S. Reed and G. Solomon, "Polynomial
+Codes over Certain Finite Fields," Journal of the Society for Industrial
+and Applied Mathematics 8(2) (1960), 300-304.
+"""
+
+from __future__ import annotations
+
+__all__ = ["rs_encode", "rs_decode_erasures"]
+
+
+def _check_prime_field(p: int, n: int, k: int) -> None:
+    if p < 2 or any(p % d == 0 for d in range(2, int(p**0.5) + 1)):
+        raise ValueError(f"p = {p} must be prime")
+    if not 0 < k <= n <= p:
+        raise ValueError("need 0 < k <= n <= p")
+
+
+def rs_encode(message, n: int, p: int) -> list:
+    r"""Encode `message` as the values :math:`m(0), m(1), \dots, m(n-1)` of its polynomial over :math:`\mathrm{GF}(p)`.
+
+    Parameters
+    ----------
+    message : sequence of int
+        The :math:`k` message symbols, each in ``range(p)``; ``message[i]``
+        is the coefficient of :math:`x^i`.
+    n : int
+        Codeword length, :math:`k \le n \le p`.
+    p : int
+        A prime field size.
+
+    Returns
+    -------
+    list of int
+
+    Examples
+    --------
+    >>> rs_encode([3, 1], n=5, p=7)  # m(x) = 3 + x at x = 0..4
+    [3, 4, 5, 6, 0]
+    """
+    message = [int(c) % p for c in message]
+    _check_prime_field(p, n, len(message))
+    codeword = []
+    for x in range(n):
+        value = 0
+        for c in reversed(message):
+            value = (value * x + c) % p
+        codeword.append(value)
+    return codeword
+
+
+def rs_decode_erasures(received, k: int, p: int) -> list:
+    r"""Recover a :math:`k`-symbol message from a codeword with erased symbols.
+
+    Lagrange-interpolates the unique polynomial of degree below
+    :math:`k` through any :math:`k` surviving positions, working exactly
+    in :math:`\mathrm{GF}(p)`.
+
+    Parameters
+    ----------
+    received : sequence
+        The codeword, with ``None`` at each erased position.
+    k : int
+        Message length.
+    p : int
+        The prime field size used to encode.
+
+    Returns
+    -------
+    list of int
+        The message symbols (polynomial coefficients, lowest degree first).
+
+    Examples
+    --------
+    >>> codeword = rs_encode([2, 5, 1], n=6, p=11)
+    >>> damaged = [None, codeword[1], None, codeword[3], codeword[4], None]
+    >>> rs_decode_erasures(damaged, k=3, p=11)
+    [2, 5, 1]
+    """
+    _check_prime_field(p, len(received), k)
+    points = [(x, int(y) % p) for x, y in enumerate(received) if y is not None][:k]
+    if len(points) < k:
+        raise ValueError(f"only {len(points)} symbols survive; at least k = {k} are needed")
+    coeffs = [0] * k
+    for i, (xi, yi) in enumerate(points):
+        basis = [1]  # the Lagrange basis polynomial prod_{j != i} (x - xj) / (xi - xj)
+        denominator = 1
+        for j, (xj, _) in enumerate(points):
+            if j == i:
+                continue
+            basis = [((basis[t - 1] if t > 0 else 0) - xj * (basis[t] if t < len(basis) else 0)) % p for t in range(len(basis) + 1)]
+            denominator = denominator * (xi - xj) % p
+        scale = yi * pow(denominator, p - 2, p) % p
+        for t, b in enumerate(basis):
+            coeffs[t] = (coeffs[t] + scale * b) % p
+    return coeffs

{mathematicskit-0.2.0 → mathematicskit-0.2.1}/mathematicskit/abstract_algebra/systems/finite_fields.py

@@ -40,10 +40,19 @@ def is_irreducible(poly: Polynomial) -> bool:
     True
     >>> is_irreducible(Polynomial([0, 1, 1], modulus=2))  # x^2+x = x(x+1): reducible
     False
+    >>> is_irreducible(Polynomial([1], modulus=2))  # the constant 1 is a unit, not irreducible
+    False
+    >>> is_irreducible(Polynomial([0], modulus=2))  # nor is the zero polynomial
+    False
     """
     p = poly.modulus
     n = poly.degree
-    if n <= 1:
+    if n < 1:
+        # Degree 0 is a nonzero constant (a unit) and degree -1 is the zero
+        # polynomial; by definition neither is irreducible, since
+        # irreducibility asks for a non-unit with no non-unit factorization.
+        return False
+    if n == 1:
         return True
     for d in range(1, n // 2 + 1):
         for candidate_coeffs in _monic_polynomials_of_degree(p, d):

{mathematicskit-0.2.0 → mathematicskit-0.2.1}/mathematicskit/abstract_algebra/systems/groups.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 from mathematicskit.abstract_algebra.core.base import FiniteGroup, GroupPropertiesResult
 
-__all__ = ["CyclicGroup", "PermutationGroup", "group_properties"]
+__all__ = ["CyclicGroup", "PermutationGroup", "DihedralGroup", "QuaternionGroup", "group_properties"]
 
 
 class CyclicGroup(FiniteGroup):
@@ -137,6 +137,115 @@ class PermutationGroup(FiniteGroup):
         return tuple(inv)
 
 
+class DihedralGroup(PermutationGroup):
+    r"""The dihedral group :math:`D_n` of symmetries of a regular ``n``-gon, of order :math:`2n`.
+
+    Realized as permutations of the polygon's vertices ``0, ..., n-1``,
+    generated by the rotation :math:`r: i \mapsto i+1 \pmod n` and the
+    reflection :math:`s: i \mapsto -i \pmod n`. Felix Klein's 1872
+    Erlangen program made groups like this -- the transformations that
+    preserve a figure -- the organizing principle of geometry. See
+    Dummit & Foote, *Abstract Algebra*, 3rd ed., Sec. 1.2.
+
+    Parameters
+    ----------
+    n : int
+        Number of polygon vertices, ``n >= 3``.
+
+    Examples
+    --------
+    >>> d4 = DihedralGroup(4)  # symmetries of a square
+    >>> d4.order
+    8
+    >>> d4.is_abelian()
+    False
+    """
+
+    def __init__(self, n: int):
+        if n < 3:
+            raise ValueError("n must be >= 3")
+        self.n = int(n)
+        rotation = tuple((i + 1) % n for i in range(n))
+        reflection = tuple((-i) % n for i in range(n))
+        super().__init__(n, generators=[rotation, reflection])
+
+    @property
+    def rotation(self) -> tuple:
+        """tuple: The generating rotation by one vertex."""
+        return self.generators[0]
+
+    @property
+    def reflection(self) -> tuple:
+        """tuple: The generating reflection through vertex 0."""
+        return self.generators[1]
+
+
+_QUATERNION_UNIT_PRODUCTS = {
+    ("1", "1"): (1, "1"),
+    ("1", "i"): (1, "i"),
+    ("1", "j"): (1, "j"),
+    ("1", "k"): (1, "k"),
+    ("i", "1"): (1, "i"),
+    ("j", "1"): (1, "j"),
+    ("k", "1"): (1, "k"),
+    ("i", "i"): (-1, "1"),
+    ("j", "j"): (-1, "1"),
+    ("k", "k"): (-1, "1"),
+    ("i", "j"): (1, "k"),
+    ("j", "k"): (1, "i"),
+    ("k", "i"): (1, "j"),
+    ("j", "i"): (-1, "k"),
+    ("k", "j"): (-1, "i"),
+    ("i", "k"): (-1, "j"),
+}
+
+
+class QuaternionGroup(FiniteGroup):
+    r"""The quaternion group :math:`Q_8 = \{\pm1, \pm i, \pm j, \pm k\}` under quaternion multiplication.
+
+    Elements are the strings ``"1", "-1", "i", "-i", "j", "-j", "k", "-k"``,
+    multiplied by William Rowan Hamilton's 1843 rules
+    :math:`i^2 = j^2 = k^2 = ijk = -1`. It is the smallest non-abelian
+    group in which every subgroup is normal. See Dummit & Foote,
+    *Abstract Algebra*, 3rd ed., Sec. 1.5.
+
+    Examples
+    --------
+    >>> q = QuaternionGroup()
+    >>> q.operate("i", "j"), q.operate("j", "i")
+    ('k', '-k')
+    >>> q.operate(q.operate("i", "j"), "k")  # ijk = -1
+    '-1'
+    >>> q.element_order("i")
+    4
+    """
+
+    _ELEMENTS = ["1", "-1", "i", "-i", "j", "-j", "k", "-k"]
+
+    @property
+    def elements(self) -> list:
+        return list(self._ELEMENTS)
+
+    def identity(self) -> str:
+        return "1"
+
+    @staticmethod
+    def _split(a: str) -> tuple:
+        return (-1, a[1:]) if a.startswith("-") else (1, a)
+
+    def operate(self, a: str, b: str) -> str:
+        sa, ua = self._split(a)
+        sb, ub = self._split(b)
+        s, u = _QUATERNION_UNIT_PRODUCTS[(ua, ub)]
+        return u if sa * sb * s == 1 else "-" + u
+
+    def inverse(self, a: str) -> str:
+        sign, unit = self._split(a)
+        if unit == "1":
+            return a
+        return unit if sign == -1 else "-" + unit
+
+
 def group_properties(group: FiniteGroup) -> GroupPropertiesResult:
     """Summarize a finite group's order, abelian-ness, and every element's order.