quatint 0.0.6__cp310-cp310-macosx_11_0_arm64.whl

quatint-0.0.6.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: quatint
+Version: 0.0.6
+Summary: A quatint class, for using quaternions backed by integers and half-integers (Hurwitz integers).
+Author-email: Ryan Heard <ryanwheard@gmail.com>
+License: MIT
+Project-URL: Repository, https://github.com/rheard/quatint
+Keywords: complex,math
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sympy<=1.12.1
+Dynamic: license
+Dynamic: license-file
+
+# quatint
+
+Exact (integer-backed) quaternion arithmetic for the **Hurwitz integers**.
+
+`quatint` provides a fast, mypyc-friendly `hurwitzint` type that behaves like a small, practical numeric object: addition/subtraction/multiplication/power, norms and conjugation, plus **left/right Euclidean division**, **left/right gcd**, and **deterministic factorization** utilities.
+
+## Why this exists
+
+Python’s built-in numeric types don’t provide an exact, integer-backed quaternion type—especially not one that can represent the Hurwitz order `(a + b i + c j + d k) / 2` without floating point.
+
+`quatint` keeps everything as integers under the hood while still letting you work with both:
+- **Lipschitz integers**: $a, b, c, d ∈ Z$
+- **Hurwitz “half” integers**: $(a + b i + c j + d k)/2$ with a parity constraint
+
+## Key features
+
+- **Exact arithmetic** (no floats required for quaternion values)
+- **Hurwitz order representation** with parity enforcement
+- **Non-commutative multiplication**
+- **Reduced norm** $N(q) ∈ Z$ and quaternion conjugation
+- **Euclidean division** (norm-Euclidean) via:
+  - `divmod(a, b)` for **left-quotient** division (`a = q*b + r`)
+  - `a.rdivmod(b)` (or `quatint.rdivmod(a, b)`) for **right-quotient** division (`a = b*q + r`)
+- **Left/right gcd** (`gcd_left`, `gcd_right`) built on the corresponding division
+- **Deterministic factorization** into `content`, `unit`, and Hurwitz primes (by prime norms)
+
+## Installation
+
+```bash
+python -m pip install quatint
+````
+
+This project is designed to compile cleanly with **mypyc** for speed (CI/test setups often ensure the compiled artifact is what’s running).
+
+## Quick start
+
+```python
+from quatint import hurwitzint
+
+a = hurwitzint(1, 2, 3, 4)
+b = hurwitzint(2, 3, 4, 5)
+
+print(a)         # (1+2i+3j+4k)
+print(a * b)     # quaternion product (non-commutative)
+print(b * a)     # generally different
+```
+
+### Half-integers (Hurwitz elements)
+
+Use `half=True` to provide numerator components of a `/2` element:
+
+```python
+from quatint import hurwitzint
+
+h = hurwitzint(1, 3, 5, 7, half=True)
+print(h)  # (1+3i+5j+7k)/2
+```
+
+### Division (left-quotient)
+
+`divmod(a, b)` defines quotient on the **left**:
+
+```python
+from quatint import hurwitzint
+
+a = hurwitzint(2, 3, 4, 53)
+b = hurwitzint(1, 2, 3, 4)
+
+q, r = divmod(a, b)
+assert q * b + r == a
+```
+
+### Right-division (right-quotient)
+
+Use `rdivmod` (method or helper) to define quotient on the **right**:
+
+```python
+from quatint import hurwitzint, rdivmod
+
+a = hurwitzint(2, 3, 4, 53)
+b = hurwitzint(1, 2, 3, 4)
+
+q, r = rdivmod(a, b)
+assert b * q + r == a
+```
+
+### GCD (left and right)
+
+Because multiplication is non-commutative, there are *two* natural gcd notions:
+
+```python
+from quatint import hurwitzint
+
+a = hurwitzint(2, 3, 4, 53)
+b = hurwitzint(1, 2, 3, 4)
+
+gl = a.gcd_left(b)    # common left divisor (a = gl*x, b = gl*y)
+gr = a.gcd_right(b)   # common right divisor (a = x*gr, b = y*gr)
+```
+
+### Factorization
+
+Factorization returns a compact normal form:
+
+* `content`: maximal positive integer scalar dividing the element (in the Hurwitz sense)
+* `unit`: a norm-1 Hurwitz unit (deterministically chosen)
+* `primes`: Hurwitz primes (each with prime rational norm), normalized via unit migration
+
+```python
+from quatint import hurwitzint
+
+n = hurwitzint(2, 3, 4, 53)
+
+fr = n.factor_right()
+assert fr.prod_right() == n
+
+fl = n.factor_left()
+assert fl.prod_left() == n
+```
+
+## Representation & guarantees
+
+### Internal representation
+
+Values are stored in **numerator units**:
+
+> `(A + B i + C j + D k) / 2`
+
+This means:
+
+* Lipschitz integers are stored with **even** numerators.
+* True Hurwitz half-integers are stored with **odd** numerators.
+* The constructor enforces the parity constraint.
+
+### Scalar coercions
+
+`int` and `float` inputs are accepted as scalars and converted via `int(...)` (i.e., truncation semantics). Quaternion values themselves remain exact.
+
+## Public API (high level)
+
+* `hurwitzint(a=0, b=0, c=0, d=0, *, half=False)`
+* `hurwitzint.conjugate()`
+* `abs(h)` → reduced norm `N(h)` (an `int`)
+* `divmod(a, b)` → left-quotient Euclidean division
+* `a.rdivmod(b)` / `rdivmod(a, b)` → right-quotient Euclidean division
+* `a.gcd_left(b)` / `gcd_left(a, b)`
+* `a.gcd_right(b)` / `gcd_right(a, b)`
+* `a.factor_left()` / `a.factor_right()` → `HurwitzFactorization`
+* `HurwitzFactorization.prod_left()` / `.prod_right()`

quatint-0.0.6.dist-info/RECORD

@@ -0,0 +1,10 @@
+3a49525171c7d4218706__mypyc.cpython-310-darwin.so,sha256=d7ojk4kagK1csDZa-LDGsAL2Ngu_utrwxzNm44BxlTo,442592
+quatint/quat.cpython-310-darwin.so,sha256=DYWuvS3p3HFnAvjdO7CaVIvaE3d1zMCf0-pIFwwkAlI,50584
+quatint/__init__.cpython-310-darwin.so,sha256=TZ6lDEaClc-LdudorMbw_V0_QjoLgTlyHwbPfVmclxU,50592
+quatint-0.0.6.dist-info/RECORD,,
+quatint-0.0.6.dist-info/WHEEL,sha256=11kMdE9gzbsaQG30fRcsAYxBLEVRsqJo098Y5iL60Xo,136
+quatint-0.0.6.dist-info/top_level.txt,sha256=5Ii4PDUZslezIEwK0uNjzWWkUXsBRi96NKCuuYLNDGA,50
+quatint-0.0.6.dist-info/METADATA,sha256=XeaEm7oRzfvTwT_wrDaw1ScafiFLAjpDeSzc_BAl8RY,5273
+quatint-0.0.6.dist-info/licenses/LICENSE,sha256=2bm9uFabQZ3Ykb_SaSU_uUbAj2-htc6WJQmS_65qD00,1073
+quatint-stubs/quat.pyi,sha256=gyebchLIv9z7nbCbezFsiLC5Pnpm-7OnxJZIxWU7V9I,3044
+quatint-stubs/__init__.pyi,sha256=QvqwCQcUL96TTqoLt-TGx36pkZMvhAmcb2QfQBhmnm8,166

quatint-0.0.6.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: false
+Tag: cp310-cp310-macosx_11_0_arm64
+Generator: delocate 0.13.0
+

quatint-0.0.6.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+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.

quatint-0.0.6.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+3a49525171c7d4218706__mypyc
+quatint
+quatint-stubs

quatint-stubs/__init__.pyi

@@ -0,0 +1 @@
+from quatint.quat import gcd_left as gcd_left, gcd_right as gcd_right, hurwitzint as hurwitzint, prod_left as prod_left, prod_right as prod_right, rdivmod as rdivmod

quatint-stubs/quat.pyi

@@ -0,0 +1,70 @@
+from _typeshed import Incomplete
+from dataclasses import dataclass
+from typing import ClassVar, Iterable, Iterator, Literal
+
+OTHER_OP_TYPES = int | float
+OP_TYPES: Incomplete
+
+@dataclass(frozen=True)
+class HurwitzFactorization:
+    content: int
+    unit: hurwitzint
+    primes: tuple['hurwitzint', ...]
+    direction: Literal['left', 'right']
+    def prod(self): ...
+    def prod_right(self): ...
+    def prod_left(self): ...
+
+def mod_sqrt_prime(n: int, p: int) -> int | None: ...
+
+class hurwitzint:
+    a: int
+    b: int
+    c: int
+    d: int
+    UNITS: ClassVar[list['hurwitzint']]
+    def __init__(self, a: int = 0, b: int = 0, c: int = 0, d: int = 0, *, half: bool = False) -> None: ...
+    @property
+    def is_lipschitz(self) -> bool: ...
+    @property
+    def den(self) -> int: ...
+    def conjugate(self) -> hurwitzint: ...
+    def components2(self) -> tuple[int, int, int, int]: ...
+    def __add__(self, other: OP_TYPES) -> hurwitzint: ...
+    def __radd__(self, other: OTHER_OP_TYPES) -> hurwitzint: ...
+    def __sub__(self, other: OP_TYPES) -> hurwitzint: ...
+    def __rsub__(self, other: OTHER_OP_TYPES) -> hurwitzint: ...
+    def __neg__(self) -> hurwitzint: ...
+    def __pos__(self) -> hurwitzint: ...
+    def __mul__(self, other: OP_TYPES) -> hurwitzint: ...
+    def __rmul__(self, other: OTHER_OP_TYPES) -> hurwitzint: ...
+    def __pow__(self, exp: int) -> hurwitzint: ...
+    def __divmod__(self, other: OP_TYPES) -> tuple['hurwitzint', 'hurwitzint']: ...
+    def __truediv__(self, other: OP_TYPES) -> hurwitzint: ...
+    def __rtruediv__(self, other: OTHER_OP_TYPES) -> hurwitzint: ...
+    def __floordiv__(self, other: OP_TYPES) -> hurwitzint: ...
+    def __rfloordiv__(self, other: OTHER_OP_TYPES) -> hurwitzint: ...
+    def __mod__(self, other: OP_TYPES) -> hurwitzint: ...
+    def rdivmod(self, other: OP_TYPES) -> tuple['hurwitzint', 'hurwitzint']: ...
+    def rtruediv(self, other: OP_TYPES) -> hurwitzint: ...
+    def rfloordiv(self, other: OP_TYPES) -> hurwitzint: ...
+    def rmod(self, other: OP_TYPES) -> hurwitzint: ...
+    def __abs__(self) -> int: ...
+    def __bool__(self) -> bool: ...
+    def __iter__(self) -> Iterator[int]: ...
+    def __len__(self) -> int: ...
+    def __getitem__(self, idx: int) -> int: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __hash__(self) -> int: ...
+    def gcd_right(self, other: OP_TYPES, *, normalize: bool = True) -> hurwitzint: ...
+    def gcd_left(self, other: OP_TYPES, *, normalize: bool = True) -> hurwitzint: ...
+    def content(self) -> int: ...
+    def factor_right(self) -> HurwitzFactorization: ...
+    def factor_left(self) -> HurwitzFactorization: ...
+
+def units() -> list['hurwitzint']: ...
+def rdivmod(a: hurwitzint, b: OP_TYPES) -> tuple['hurwitzint', 'hurwitzint']: ...
+def gcd_left(a: hurwitzint, b: OP_TYPES) -> hurwitzint: ...
+def gcd_right(a: hurwitzint, b: OP_TYPES) -> hurwitzint: ...
+def prod_right(x: Iterable[OP_TYPES], start: OP_TYPES | None = None): ...
+def prod_left(x: Iterable[OP_TYPES], start: OP_TYPES | None = None): ...