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.
- {tritlib-1.2.3 → tritlib-2.0.1}/CHANGELOG.md +67 -0
- tritlib-2.0.1/CLAUDE.md +68 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/PKG-INFO +36 -26
- {tritlib-1.2.3 → tritlib-2.0.1}/README.md +35 -25
- {tritlib-1.2.3 → tritlib-2.0.1}/pyproject.toml +1 -1
- {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/__init__.py +25 -1
- tritlib-2.0.1/src/tritlib/tfloat.py +917 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/trit.py +14 -7
- tritlib-1.2.3/src/tritlib/tryte.py → tritlib-2.0.1/src/tritlib/tritarray.py +87 -81
- {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/trits.py +10 -6
- tritlib-2.0.1/src/tritlib/trybble.py +12 -0
- tritlib-2.0.1/src/tritlib/tryte.py +12 -0
- tritlib-2.0.1/src/tritlib/word.py +59 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_tfloat.py +286 -134
- tritlib-2.0.1/tests/test_tfloat_div.py +35 -0
- tritlib-2.0.1/tests/test_tritarray.py +277 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_trits.py +47 -31
- tritlib-2.0.1/tests/test_tryte.py +26 -0
- tritlib-2.0.1/tests/test_word.py +74 -0
- tritlib-1.2.3/src/tritlib/tfloat.py +0 -675
- tritlib-1.2.3/tests/test_tryte.py +0 -247
- {tritlib-1.2.3 → tritlib-2.0.1}/.gitignore +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/LICENSE +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/py.typed +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/context.py +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/logic/__init__.py +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/logic/base.py +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/logic/bochvar.py +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/logic/heyting.py +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/logic/kleene.py +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/logic/lukasiewicz.py +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/logic/plural.py +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/src/tritlib/logic/rm3.py +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_context.py +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_logic.py +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_logic_kleene.py +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_plural.py +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_tfloat_add.py +0 -0
- {tritlib-1.2.3 → tritlib-2.0.1}/tests/test_tfloat_mul.py +0 -0
- {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
|
tritlib-2.0.1/CLAUDE.md
ADDED
|
@@ -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:
|
|
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 —
|
|
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
|
-
- **`
|
|
38
|
-
- **`
|
|
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
|
|
45
|
-
|
|
46
|
-
| **Kleene (K3)**
|
|
47
|
-
| **Łukasiewicz (L3)** | Indeterminate (ontological)
|
|
48
|
-
| **Heyting (HT)**
|
|
49
|
-
| **B3 (Bochvar)**
|
|
50
|
-
| **RM3 (R-mingle)**
|
|
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
|
-
|
|
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 =
|
|
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 =
|
|
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,
|
|
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 =
|
|
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
|
-
├──
|
|
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 `
|
|
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 —
|
|
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
|
-
- **`
|
|
16
|
-
- **`
|
|
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
|
|
23
|
-
|
|
24
|
-
| **Kleene (K3)**
|
|
25
|
-
| **Łukasiewicz (L3)** | Indeterminate (ontological)
|
|
26
|
-
| **Heyting (HT)**
|
|
27
|
-
| **B3 (Bochvar)**
|
|
28
|
-
| **RM3 (R-mingle)**
|
|
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
|
-
|
|
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 =
|
|
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 =
|
|
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,
|
|
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 =
|
|
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
|
-
├──
|
|
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 `
|
|
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>
|
|
@@ -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__ = [
|
|
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
|
+
]
|