tritlib 1.2.3__tar.gz → 2.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of tritlib might be problematic. Click here for more details.

Files changed (40) hide show
  1. {tritlib-1.2.3 → tritlib-2.0.1}/CHANGELOG.md +67 -0
  2. tritlib-2.0.1/CLAUDE.md +68 -0
  3. {tritlib-1.2.3 → tritlib-2.0.1}/PKG-INFO +36 -26
  4. {tritlib-1.2.3 → tritlib-2.0.1}/README.md +35 -25
  5. {tritlib-1.2.3 → tritlib-2.0.1}/pyproject.toml +1 -1
  6. {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/__init__.py +25 -1
  7. tritlib-2.0.1/src/tritlib/tfloat.py +917 -0
  8. {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/trit.py +14 -7
  9. tritlib-1.2.3/src/tritlib/tryte.py → tritlib-2.0.1/src/tritlib/tritarray.py +87 -81
  10. {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/trits.py +10 -6
  11. tritlib-2.0.1/src/tritlib/trybble.py +12 -0
  12. tritlib-2.0.1/src/tritlib/tryte.py +12 -0
  13. tritlib-2.0.1/src/tritlib/word.py +59 -0
  14. {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_tfloat.py +286 -134
  15. tritlib-2.0.1/tests/test_tfloat_div.py +35 -0
  16. tritlib-2.0.1/tests/test_tritarray.py +277 -0
  17. {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_trits.py +47 -31
  18. tritlib-2.0.1/tests/test_tryte.py +26 -0
  19. tritlib-2.0.1/tests/test_word.py +74 -0
  20. tritlib-1.2.3/src/tritlib/tfloat.py +0 -675
  21. tritlib-1.2.3/tests/test_tryte.py +0 -247
  22. {tritlib-1.2.3 → tritlib-2.0.1}/.gitignore +0 -0
  23. {tritlib-1.2.3 → tritlib-2.0.1}/LICENSE +0 -0
  24. {tritlib-1.2.3 → tritlib-2.0.1}/py.typed +0 -0
  25. {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/context.py +0 -0
  26. {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/logic/__init__.py +0 -0
  27. {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/logic/base.py +0 -0
  28. {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/logic/bochvar.py +0 -0
  29. {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/logic/heyting.py +0 -0
  30. {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/logic/kleene.py +0 -0
  31. {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/logic/lukasiewicz.py +0 -0
  32. {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/logic/plural.py +0 -0
  33. {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/logic/rm3.py +0 -0
  34. {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_context.py +0 -0
  35. {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_logic.py +0 -0
  36. {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_logic_kleene.py +0 -0
  37. {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_plural.py +0 -0
  38. {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_tfloat_add.py +0 -0
  39. {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_tfloat_mul.py +0 -0
  40. {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_trit.py +0 -0
@@ -4,6 +4,73 @@ All notable changes to this project will be documented in this file.
4
4
 
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
6
6
 
7
+ ## [2.0.0] — 2026-05-18
8
+
9
+ ### Breaking
10
+ - `Tryte` is now a fixed-width 9-trit type (T9), aligned with Setnex ISA v0.8.
11
+ Its constructor no longer accepts a `width` argument. Code that did
12
+ `Tryte(value, w)` for `w ≠ 9` must migrate to `TritArray(value, w)`.
13
+ - The arbitrary-width balanced ternary word type historically named `Tryte`
14
+ is renamed `TritArray`. All public methods (`add_with_carry`,
15
+ `add_saturating`, `to_width`, `set`, `__divmod__`, shifts, rotations,
16
+ consensus, etc.) live on `TritArray` and are inherited by the three
17
+ width-locked subclasses.
18
+
19
+ ### Added
20
+ - `TritArray(value, width)` — arbitrary-width balanced ternary word (the
21
+ generic base type).
22
+ - `Trybble(value)` — 3-trit field (T3), the smallest addressable grouping
23
+ per the ISA.
24
+ - `Word(value)` — 27-trit word (T27), the basic memory and register unit
25
+ per the ISA.
26
+ - Subclasses share `TritArray`'s implementation and preserve their concrete
27
+ type through arithmetic via `type(self)._from_trits(...)` dispatch.
28
+ - `tests/test_tritarray.py` — generic-width regression suite migrated from
29
+ the former `test_tryte.py`; `test_tryte.py` now exercises the 9-trit
30
+ semantics (overflow at ±9841, fixed `len() == 9`, etc.).
31
+
32
+ ### Changed
33
+ - All internal `TFloat` arithmetic (mantissa, regime, exponent, work-scale
34
+ bounds, double-width products, division work widths) routes through
35
+ `TritArray`. `TFloat._raw` is a `TritArray` of even width ≥ 8; the
36
+ constructor accepts `float | int | TritArray` (any subclass instance
37
+ whose width meets Tekum's even-and-≥-8 rule).
38
+ - `to_width(w)` on any subclass returns a `TritArray` (changing width
39
+ exits the width-locked contract).
40
+ - `__init__.py` exports `TritArray`, `Trybble`, `Word` alongside `Tryte`.
41
+
42
+ ## [1.3.0] — 2026-04-29
43
+
44
+ ### Added
45
+ - Native trit-level division on `TFloat` (Tekum arithmetic)
46
+ - Mantissa division at a working scale `p_work = max(p_self, p_other) + 2`
47
+ - Numerator pre-shifted by `3^p_work` to recover the fractional quotient as an integer
48
+ - Wheel-algebra special-value handling: `x/0 = ∞`, `0/0 = NaR`, `x/∞ = 0`, `∞/x = ∞`, `∞/∞ = NaR`
49
+ - Result re-encoded by `_finalize`; no longer routes through Python `float`
50
+
51
+ ### Fixed
52
+ - `Trits.__divmod__` and `Tryte.__divmod__` exponential drift on certain operand magnitudes.
53
+ Initial `partial_rest = s[:len(d)-1]` could already exceed `|d|/2` when `|d|` sat at the
54
+ lower end of its trit-length range, breaking the single-trit quotient invariant; the
55
+ resulting remainder grew geometrically and the correction loop ran for billions of
56
+ iterations. Both implementations now start with `partial_rest = []` and `pr = 0`,
57
+ consuming every trit of the dividend and maintaining `|pr| ≤ |d|/2` at every step.
58
+ - `Tryte.__divmod__` silent overflow at width boundaries: the quotient-digit decision
59
+ `V + V > abs_other` truncated when `2|V|` exceeded the Tryte range (e.g. width 26 with
60
+ values near `3²⁶/2`). The decision now uses an `int` comparison, immune to truncation.
61
+
62
+ ### Changed
63
+ - `TFloat._from_float` (renamed from `from_float`): privatized; bounded fraction
64
+ quantification with `_find_regime` recomputed in-loop, plus a final clamp
65
+ - `_finalize` factored out of `__add__`, `__mul__`, and `__truediv__` for shared
66
+ normalization and re-encoding
67
+ - `Trits.__divmod__` and `Tryte.__divmod__` now raise `TypeError` (not return
68
+ `NotImplemented`) when the divisor is of the wrong type, matching `divmod` protocol
69
+ - `TFloat.__eq__` returns `NotImplemented` for cross-width comparisons rather than
70
+ silently coercing
71
+ - `Tryte.to_tryte` (TFloat method): correct slicing for the `e == 0` and `e < 0`
72
+ edge cases, plus explicit overflow guard when `e ≥ width`
73
+
7
74
  ## [1.2.3] — 2026-04-22
8
75
  - added TFloat conversion from and into int/Tryte/Trits
9
76
  - renamed to_tryte into to_raw
@@ -0,0 +1,68 @@
1
+ # CLAUDE.md
2
+
3
+ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+ ## Règle absolue
6
+
7
+ **Il t'est interdit de coder.** Tu ne dois jamais modifier la logique d'un fichier `.py` de ce dépôt. La seule modification autorisée dans un fichier `.py` est l'écriture ou la mise à jour de **docstrings**, et uniquement lorsque l'utilisateur le demande explicitement. Toute autre édition de code (ajout/suppression de fonctions, modification d'une expression, refactoring, correction de bug, etc.) est interdite, même si elle semble triviale ou évidente. Lecture, recherche, analyse et explication restent autorisées.
8
+
9
+ ## Commands
10
+
11
+ Setup and test:
12
+ ```bash
13
+ python -m venv .venv
14
+ source .venv/bin/activate
15
+ pip install -e ".[dev]"
16
+ python -m pytest # full suite
17
+ python -m pytest tests/test_tfloat.py # single file
18
+ python -m pytest tests/test_tfloat.py::test_name # single test
19
+ python -m pytest --cov=tritlib # with coverage
20
+ ```
21
+
22
+ Build distribution: `python -m build` (hatchling backend, declared in `pyproject.toml`).
23
+
24
+ Python ≥ 3.11 required. No runtime dependencies — only `pytest` and `pytest-cov` for dev.
25
+
26
+ ## Architecture
27
+
28
+ ### Layering of the core types
29
+
30
+ `Trit` → `Trits` → `TritArray` → `TFloat`. Each layer is built on the one below and they must be edited consistent with that direction:
31
+
32
+ - **`Trit`** (`trit.py`) — single balanced ternary digit ∈ {N, Z, P}. Provides `half_add`/`full_add` returning `(sum, carry)` where carry is itself a Trit (ternary carry, not binary).
33
+ - **`Trits`** (`trits.py`) — arbitrary-precision balanced ternary integer, built as a tuple of `Trit` in **little-endian** order. Division uses the double trial quotient method; result follows symmetric Euclidean semantics (remainder may be negative).
34
+ - **`TritArray`** (`tritarray.py`) — fixed-width register-like word at arbitrary width. Three addition modes (`__add__` truncates, `add_with_carry` returns `(result, carry: Trit)`, `add_saturating` clamps). Operations construct via `type(self)._from_trits(trits, width)` (subclass-preserving dispatch) which truncates rather than raising — this is intentional hardware simulation behaviour.
35
+ - **`Trybble`** / **`Tryte`** / **`Word`** (`trybble.py`, `tryte.py`, `word.py`) — width-locked subclasses (3 / 9 / 27 trits) aligned with Setnex ISA v0.8. Each declares a `WIDTH` class attribute, an `__init__(self, value)` that forwards to `TritArray.__init__(value, WIDTH)`, and an override of `_from_trits` that ignores any `width` argument and forces `WIDTH`. Arithmetic between same-typed instances preserves the subtype via `type(self)._from_trits`. `to_width(w)` on a subclass returns a base `TritArray` (changing width exits the locked contract).
36
+ - **`TFloat`** (`tfloat.py`) — Tekum tapered precision float (arXiv:2512.10964). Stores raw as a `TritArray` (even width ≥ 8, not necessarily 9 or 27). Regime/exponent/fraction/sign are properties derived on demand. Arithmetic (`+`, `*`, `/`) is implemented natively at the trit level via `TritArray` operations (mantissa, double-width products, work-scale bounds), then re-encoded through `_finalize`.
37
+
38
+ All types are **immutable**: `__setattr__` raises, `__slots__` enforces fields, and every operation returns a new instance. Do not add mutators.
39
+
40
+ Internal storage is **little-endian** (least significant trit first), but string repr and constructor input strings are **big-endian** (`"+-0+"` reads MSB-to-LSB). Watch this direction reversal when editing.
41
+
42
+ ### Logic-system dispatch
43
+
44
+ The five logic systems live in `src/tritlib/logic/`. Each subclasses `TernaryLogic` (in `base.py`) and only needs to override the operators where it diverges from defaults (most override only `imply_op`).
45
+
46
+ `Trit`'s `&`, `|`, `~`, and `imply` look up the active logic via a `ContextVar` (`_current_logic` in `context.py`). When unset, fast inlined Kleene paths are used (no dispatch overhead). The `logic_mode(system)` context manager swaps the active system for the duration of a `with` block. New logic systems should be added by subclassing `TernaryLogic` and exporting from `logic/__init__.py`.
47
+
48
+ `pluralize` (in `logic/plural.py`) evaluates a callable across all five systems and reports convergence/divergence — use it when reasoning about whether an expression is logic-system-sensitive.
49
+
50
+ ### Tekum format invariants
51
+
52
+ When touching `TFloat`:
53
+ - Width must be **even and ≥ 8**. Constructors validate this.
54
+ - Three special values are stored as the raw `Tryte`: zero (all Z), infinity (all P), NaR (all N). The `_special` slot caches which one. Arithmetic on specials follows **wheel-algebra** semantics (e.g., `x/0 = ∞`, `0/0 = NaR`, `∞/∞ = NaR`) — see `__add__`, `__mul__`, `__truediv__` for the dispatch tables.
55
+ - Tekum's defining property: **truncation is rounding**. When reducing precision, slice the anchor; no carry propagation needed. The `_finalize` helper centralises this.
56
+ - Cross-width `==` returns `NotImplemented` (no silent coercion).
57
+ - `from_float` is the private `_from_float` since 1.3.0; external callers should use the `TFloat(value, width=…)` constructor.
58
+
59
+ ### Division pitfalls (Trits / TritArray)
60
+
61
+ The 1.3.0 fix is load-bearing: `__divmod__` starts with `partial_rest = []` and `pr = 0`, then consumes every trit of the dividend while maintaining `|pr| ≤ |d|/2`. The previous shortcut of pre-loading `partial_rest = s[:len(d)-1]` could violate the invariant for divisors at the low end of their trit-length range and caused exponential drift. Do not "optimise" this back. The single-trit quotient decision must use a true `int` comparison (`V + V > abs_other`), not a `TritArray` comparison that could truncate.
62
+
63
+ ## Conventions to follow
64
+
65
+ - Type-hinted, immutable, dunder-rich public API. Add `__hash__`, `__eq__`, and `@total_ordering` where comparable; raise `AttributeError` from `__setattr__`.
66
+ - Operators returning `NotImplemented` (not raising) for unsupported operand types — except `__divmod__`, which raises `TypeError` to match Python's `divmod` protocol.
67
+ - New public symbols must be re-exported from the appropriate `__init__.py` and added to `__all__`.
68
+ - Docstrings on public classes and methods; the project ships `py.typed` for downstream mypy users.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: tritlib
3
- Version: 1.2.3
3
+ Version: 2.0.1
4
4
  Summary: Balanced ternary arithmetic and multi-valued logic library
5
5
  Project-URL: Homepage, https://codeberg.org/setnex-org/tritlib
6
6
  Project-URL: Repository, https://codeberg.org/setnex-org/tritlib
@@ -20,7 +20,7 @@ Requires-Dist: pytest; extra == 'dev'
20
20
  Requires-Dist: pytest-cov; extra == 'dev'
21
21
  Description-Content-Type: text/markdown
22
22
 
23
- # tritlib — v1.2
23
+ # tritlib — v2.0
24
24
 
25
25
  A pure Python library for balanced ternary arithmetic, multi-valued logic, and floating-point representation.
26
26
 
@@ -34,20 +34,21 @@ Balanced ternary is a base-3 numeral system using digits from {−1, 0, +1}. It
34
34
 
35
35
  - **`Trit`** — Immutable single trit. Arithmetic (negation, multiplication, half/full addition with ternary carry), Kleene K3 logic (`&`, `|`, `~`), consensus and anti-consensus operators. Hashable and comparable.
36
36
  - **`Trits`** — Arbitrary-precision balanced ternary integer. Full arithmetic: addition, subtraction, multiplication, floor division and modulo via the double trial quotient method. Constructed from `int` or balanced ternary string (`"+-0+"`).
37
- - **`Tryte`** — Fixed-width ternary word, analogous to a hardware register. Three addition modes: truncating (wrap around), with carry, and saturating. Shifts, rotations, trit-level access and modification, sign extraction, absolute value, consensus/anti-consensus. Resizable across widths.
38
- - **`TFloat`** — Balanced ternary floating-point number using the Tekum tapered precision format (Hunhold, arXiv:2512.10964). No sign trit, truncation equals rounding, three special values (zero, infinity, NaR). Configurable width (even, ≥ 8). Addition and multiplication use native trit-level arithmetic; division converts via Python `float`.
37
+ - **`TritArray`** — Fixed-width ternary word at arbitrary width, analogous to a hardware register. Three addition modes: truncating (wrap around), with carry, and saturating. Shifts, rotations, trit-level access and modification, sign extraction, absolute value, consensus/anti-consensus. Resizable across widths via `to_width`.
38
+ - **`Trybble`** / **`Tryte`** / **`Word`** — Width-locked subclasses of `TritArray` matching the Setnex ISA unit hierarchy: 3 trits (T3, register address / sub-opcode), 9 trits (T9, byte-analogue), and 27 trits (T27, memory and register word). All inherit `TritArray`'s arithmetic and preserve their concrete type through operations.
39
+ - **`TFloat`** — Balanced ternary floating-point number using the Tekum tapered precision format (Hunhold, arXiv:2512.10964). No sign trit, truncation equals rounding, three special values (zero, infinity, NaR). Configurable width (even, ≥ 8). Addition, multiplication and division all use native trit-level arithmetic with wheel-algebra semantics for the special values.
39
40
 
40
41
  ### Multi-valued logic
41
42
 
42
43
  Five ternary logic systems, selectable at runtime via a common abstract interface:
43
44
 
44
- | System | Third value semantics | Key difference |
45
- |---|---|---|
46
- | **Kleene (K3)** | Unknown (epistemic) | Default. AND = min, OR = max |
47
- | **Łukasiewicz (L3)** | Indeterminate (ontological) | Z → Z yields P (tautological self-implication) |
48
- | **Heyting (HT)** | Non-proved (constructivist) | ~Z = N (unproved is false) |
49
- | **B3 (Bochvar)** | Both true and false (paraconsistent) | Z ∧ Z = N (contradiction resolves downward) |
50
- | **RM3 (R-mingle)** | Relevant entailment | Restricted implication |
45
+ | System | Third value semantics | Key difference |
46
+ | -------------------- | ------------------------------------ | ---------------------------------------------- |
47
+ | **Kleene (K3)** | Unknown (epistemic) | Default. AND = min, OR = max |
48
+ | **Łukasiewicz (L3)** | Indeterminate (ontological) | Z → Z yields P (tautological self-implication) |
49
+ | **Heyting (HT)** | Non-proved (constructivist) | ~Z = N (unproved is false) |
50
+ | **B3 (Bochvar)** | Both true and false (paraconsistent) | Z ∧ Z = N (contradiction resolves downward) |
51
+ | **RM3 (R-mingle)** | Relevant entailment | Restricted implication |
51
52
 
52
53
  Each system implements NOT, AND, OR, IMPLY, XOR, and EQUIV. Custom systems can be added by subclassing `TernaryLogic`. The `logic_mode` context manager switches the active logic system for operators on `Trit`. The `pluralize` function evaluates an expression across all five systems and reports convergence or divergence.
53
54
 
@@ -114,32 +115,38 @@ print(int(r)) # -4
114
115
  ### Fixed-width words
115
116
 
116
117
  ```python
117
- from tritlib import Tryte
118
+ from tritlib import TritArray, Trybble, Tryte, Word
118
119
 
119
- w = Tryte(42, width=6)
120
+ # ISA-aligned width-locked types
121
+ print(len(Trybble(1))) # 3
122
+ print(len(Tryte(42))) # 9
123
+ print(len(Word(0))) # 27
124
+
125
+ # Arbitrary width via TritArray
126
+ w = TritArray(42, width=6)
120
127
  print(len(w)) # 6
121
128
  print(w[0]) # least significant trit
122
129
 
123
- # Saturating addition
124
- result = Tryte(300, 6).add_saturating(Tryte(300, 6))
130
+ # Saturating addition (any TritArray subclass)
131
+ result = TritArray(300, 6).add_saturating(TritArray(300, 6))
125
132
  print(int(result)) # 364 (clamped to max)
126
133
 
127
134
  # Carry detection
128
- result, carry = Tryte(300, 6).add_with_carry(Tryte(65, 6))
135
+ result, carry = TritArray(300, 6).add_with_carry(TritArray(65, 6))
129
136
  print(carry) # P (positive overflow)
130
137
  ```
131
138
 
132
139
  ### Floating-point (Tekum format)
133
140
 
134
141
  ```python
135
- from tritlib import TFloat, Tryte
142
+ from tritlib import TFloat, TritArray
136
143
 
137
144
  # Encode from Python float
138
145
  tf = TFloat(3.14, width=20)
139
146
  print(float(tf)) # ≈ 3.14
140
147
 
141
- # Decode from a register word
142
- register = Tryte(1640, 8)
148
+ # Decode from a register word (even width ≥ 8)
149
+ register = TritArray(1640, 8)
143
150
  tf = TFloat(register)
144
151
  print(float(tf)) # 1.0
145
152
 
@@ -148,6 +155,7 @@ a = TFloat(2.5, width=20)
148
155
  b = TFloat(1.3, width=20)
149
156
  print(float(a + b)) # ≈ 3.8
150
157
  print(float(a * b)) # ≈ 3.25
158
+ print(float(a / b)) # ≈ 1.923
151
159
 
152
160
  # Special values
153
161
  print(TFloat(0.0, width=8)) # 0
@@ -204,7 +212,10 @@ src/tritlib/
204
212
  ├── __init__.py
205
213
  ├── trit.py # Trit type
206
214
  ├── trits.py # Trits arbitrary-precision type
207
- ├── tryte.py # Tryte fixed-width type
215
+ ├── tritarray.py # TritArray generic fixed-width type
216
+ ├── trybble.py # Trybble (T3, 3-trit subclass)
217
+ ├── tryte.py # Tryte (T9, 9-trit subclass)
218
+ ├── word.py # Word (T27, 27-trit subclass)
208
219
  ├── tfloat.py # TFloat Tekum floating-point type
209
220
  ├── context.py # Logic mode context manager
210
221
  └── logic/
@@ -239,8 +250,7 @@ python -m pytest
239
250
  - [x] Logic context manager (`with logic_mode(L3()): result = a & b`)
240
251
  - [x] Logical pluralism: evaluate across all systems, report convergence/divergence
241
252
  - [x] Tekum balanced ternary floating-point (encode, decode, arithmetic via float)
242
- - [x] Native trit-level `__add__` and `__mul__` (Tekum truncation = rounding)
243
- - [ ] Native trit-level `__truediv__` (currently converts via Python `float`)
253
+ - [x] Native trit-level `__add__`, `__mul__` and `__truediv__` (Tekum truncation = rounding)
244
254
  - [ ] Educational step-by-step computation output (carry propagation, partial products)
245
255
 
246
256
  ## License
@@ -249,7 +259,7 @@ MIT — see LICENSE file for details.
249
259
 
250
260
  ## Links
251
261
 
252
- - Repository: https://codeberg.org/setnex-org/tritlib
253
- - PyPI: https://pypi.org/project/tritlib/
254
- - Tekum paper: https://arxiv.org/abs/2512.10964
255
- - Setnex balanced ternary ISA: https://setnex.org
262
+ - Repository: <https://codeberg.org/setnex-org/tritlib>
263
+ - PyPI: <https://pypi.org/project/tritlib/>
264
+ - Tekum paper: <https://arxiv.org/abs/2512.10964>
265
+ - Setnex balanced ternary ISA: <https://setnex.org>
@@ -1,4 +1,4 @@
1
- # tritlib — v1.2
1
+ # tritlib — v2.0
2
2
 
3
3
  A pure Python library for balanced ternary arithmetic, multi-valued logic, and floating-point representation.
4
4
 
@@ -12,20 +12,21 @@ Balanced ternary is a base-3 numeral system using digits from {−1, 0, +1}. It
12
12
 
13
13
  - **`Trit`** — Immutable single trit. Arithmetic (negation, multiplication, half/full addition with ternary carry), Kleene K3 logic (`&`, `|`, `~`), consensus and anti-consensus operators. Hashable and comparable.
14
14
  - **`Trits`** — Arbitrary-precision balanced ternary integer. Full arithmetic: addition, subtraction, multiplication, floor division and modulo via the double trial quotient method. Constructed from `int` or balanced ternary string (`"+-0+"`).
15
- - **`Tryte`** — Fixed-width ternary word, analogous to a hardware register. Three addition modes: truncating (wrap around), with carry, and saturating. Shifts, rotations, trit-level access and modification, sign extraction, absolute value, consensus/anti-consensus. Resizable across widths.
16
- - **`TFloat`** — Balanced ternary floating-point number using the Tekum tapered precision format (Hunhold, arXiv:2512.10964). No sign trit, truncation equals rounding, three special values (zero, infinity, NaR). Configurable width (even, ≥ 8). Addition and multiplication use native trit-level arithmetic; division converts via Python `float`.
15
+ - **`TritArray`** — Fixed-width ternary word at arbitrary width, analogous to a hardware register. Three addition modes: truncating (wrap around), with carry, and saturating. Shifts, rotations, trit-level access and modification, sign extraction, absolute value, consensus/anti-consensus. Resizable across widths via `to_width`.
16
+ - **`Trybble`** / **`Tryte`** / **`Word`** — Width-locked subclasses of `TritArray` matching the Setnex ISA unit hierarchy: 3 trits (T3, register address / sub-opcode), 9 trits (T9, byte-analogue), and 27 trits (T27, memory and register word). All inherit `TritArray`'s arithmetic and preserve their concrete type through operations.
17
+ - **`TFloat`** — Balanced ternary floating-point number using the Tekum tapered precision format (Hunhold, arXiv:2512.10964). No sign trit, truncation equals rounding, three special values (zero, infinity, NaR). Configurable width (even, ≥ 8). Addition, multiplication and division all use native trit-level arithmetic with wheel-algebra semantics for the special values.
17
18
 
18
19
  ### Multi-valued logic
19
20
 
20
21
  Five ternary logic systems, selectable at runtime via a common abstract interface:
21
22
 
22
- | System | Third value semantics | Key difference |
23
- |---|---|---|
24
- | **Kleene (K3)** | Unknown (epistemic) | Default. AND = min, OR = max |
25
- | **Łukasiewicz (L3)** | Indeterminate (ontological) | Z → Z yields P (tautological self-implication) |
26
- | **Heyting (HT)** | Non-proved (constructivist) | ~Z = N (unproved is false) |
27
- | **B3 (Bochvar)** | Both true and false (paraconsistent) | Z ∧ Z = N (contradiction resolves downward) |
28
- | **RM3 (R-mingle)** | Relevant entailment | Restricted implication |
23
+ | System | Third value semantics | Key difference |
24
+ | -------------------- | ------------------------------------ | ---------------------------------------------- |
25
+ | **Kleene (K3)** | Unknown (epistemic) | Default. AND = min, OR = max |
26
+ | **Łukasiewicz (L3)** | Indeterminate (ontological) | Z → Z yields P (tautological self-implication) |
27
+ | **Heyting (HT)** | Non-proved (constructivist) | ~Z = N (unproved is false) |
28
+ | **B3 (Bochvar)** | Both true and false (paraconsistent) | Z ∧ Z = N (contradiction resolves downward) |
29
+ | **RM3 (R-mingle)** | Relevant entailment | Restricted implication |
29
30
 
30
31
  Each system implements NOT, AND, OR, IMPLY, XOR, and EQUIV. Custom systems can be added by subclassing `TernaryLogic`. The `logic_mode` context manager switches the active logic system for operators on `Trit`. The `pluralize` function evaluates an expression across all five systems and reports convergence or divergence.
31
32
 
@@ -92,32 +93,38 @@ print(int(r)) # -4
92
93
  ### Fixed-width words
93
94
 
94
95
  ```python
95
- from tritlib import Tryte
96
+ from tritlib import TritArray, Trybble, Tryte, Word
96
97
 
97
- w = Tryte(42, width=6)
98
+ # ISA-aligned width-locked types
99
+ print(len(Trybble(1))) # 3
100
+ print(len(Tryte(42))) # 9
101
+ print(len(Word(0))) # 27
102
+
103
+ # Arbitrary width via TritArray
104
+ w = TritArray(42, width=6)
98
105
  print(len(w)) # 6
99
106
  print(w[0]) # least significant trit
100
107
 
101
- # Saturating addition
102
- result = Tryte(300, 6).add_saturating(Tryte(300, 6))
108
+ # Saturating addition (any TritArray subclass)
109
+ result = TritArray(300, 6).add_saturating(TritArray(300, 6))
103
110
  print(int(result)) # 364 (clamped to max)
104
111
 
105
112
  # Carry detection
106
- result, carry = Tryte(300, 6).add_with_carry(Tryte(65, 6))
113
+ result, carry = TritArray(300, 6).add_with_carry(TritArray(65, 6))
107
114
  print(carry) # P (positive overflow)
108
115
  ```
109
116
 
110
117
  ### Floating-point (Tekum format)
111
118
 
112
119
  ```python
113
- from tritlib import TFloat, Tryte
120
+ from tritlib import TFloat, TritArray
114
121
 
115
122
  # Encode from Python float
116
123
  tf = TFloat(3.14, width=20)
117
124
  print(float(tf)) # ≈ 3.14
118
125
 
119
- # Decode from a register word
120
- register = Tryte(1640, 8)
126
+ # Decode from a register word (even width ≥ 8)
127
+ register = TritArray(1640, 8)
121
128
  tf = TFloat(register)
122
129
  print(float(tf)) # 1.0
123
130
 
@@ -126,6 +133,7 @@ a = TFloat(2.5, width=20)
126
133
  b = TFloat(1.3, width=20)
127
134
  print(float(a + b)) # ≈ 3.8
128
135
  print(float(a * b)) # ≈ 3.25
136
+ print(float(a / b)) # ≈ 1.923
129
137
 
130
138
  # Special values
131
139
  print(TFloat(0.0, width=8)) # 0
@@ -182,7 +190,10 @@ src/tritlib/
182
190
  ├── __init__.py
183
191
  ├── trit.py # Trit type
184
192
  ├── trits.py # Trits arbitrary-precision type
185
- ├── tryte.py # Tryte fixed-width type
193
+ ├── tritarray.py # TritArray generic fixed-width type
194
+ ├── trybble.py # Trybble (T3, 3-trit subclass)
195
+ ├── tryte.py # Tryte (T9, 9-trit subclass)
196
+ ├── word.py # Word (T27, 27-trit subclass)
186
197
  ├── tfloat.py # TFloat Tekum floating-point type
187
198
  ├── context.py # Logic mode context manager
188
199
  └── logic/
@@ -217,8 +228,7 @@ python -m pytest
217
228
  - [x] Logic context manager (`with logic_mode(L3()): result = a & b`)
218
229
  - [x] Logical pluralism: evaluate across all systems, report convergence/divergence
219
230
  - [x] Tekum balanced ternary floating-point (encode, decode, arithmetic via float)
220
- - [x] Native trit-level `__add__` and `__mul__` (Tekum truncation = rounding)
221
- - [ ] Native trit-level `__truediv__` (currently converts via Python `float`)
231
+ - [x] Native trit-level `__add__`, `__mul__` and `__truediv__` (Tekum truncation = rounding)
222
232
  - [ ] Educational step-by-step computation output (carry propagation, partial products)
223
233
 
224
234
  ## License
@@ -227,7 +237,7 @@ MIT — see LICENSE file for details.
227
237
 
228
238
  ## Links
229
239
 
230
- - Repository: https://codeberg.org/setnex-org/tritlib
231
- - PyPI: https://pypi.org/project/tritlib/
232
- - Tekum paper: https://arxiv.org/abs/2512.10964
233
- - Setnex balanced ternary ISA: https://setnex.org
240
+ - Repository: <https://codeberg.org/setnex-org/tritlib>
241
+ - PyPI: <https://pypi.org/project/tritlib/>
242
+ - Tekum paper: <https://arxiv.org/abs/2512.10964>
243
+ - Setnex balanced ternary ISA: <https://setnex.org>
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "tritlib"
7
- version = "1.2.3"
7
+ version = "2.0.1"
8
8
  description = "Balanced ternary arithmetic and multi-valued logic library"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -7,9 +7,33 @@ It supports arithmetic operations, comparisons, and conversions between strings,
7
7
 
8
8
  from .trit import Trit, N, Z, P
9
9
  from .trits import Trits
10
+ from .tritarray import TritArray
10
11
  from .tryte import Tryte
12
+ from .trybble import Trybble
13
+ from .word import Word
11
14
  from .logic import Lukasiewicz, RM3, Bochvar, HT, Kleene, K3, L3, B3, pluralize
12
15
  from .context import logic_mode
13
16
  from .tfloat import TFloat
14
17
 
15
- __all__ = ["Trit", "Trits", "Tryte", "N", "Z", "P", "Lukasiewicz", "RM3", "Bochvar", "HT", "Kleene", "logic_mode", "L3","B3","K3", "pluralize", "TFloat"]
18
+ __all__ = [
19
+ "Trit",
20
+ "Trits",
21
+ "Tryte",
22
+ "Word",
23
+ "Trybble",
24
+ "TritArray",
25
+ "N",
26
+ "Z",
27
+ "P",
28
+ "Lukasiewicz",
29
+ "RM3",
30
+ "Bochvar",
31
+ "HT",
32
+ "Kleene",
33
+ "logic_mode",
34
+ "L3",
35
+ "B3",
36
+ "K3",
37
+ "pluralize",
38
+ "TFloat",
39
+ ]