Metadata-Version: 2.4
Name: tritlib
Version: 1.0.0
Summary: Balanced ternary arithmetic and multi-valued logic library
Project-URL: Homepage, https://codeberg.org/setnex-org/tritlib
Project-URL: Repository, https://codeberg.org/setnex-org/tritlib
Project-URL: Issues, https://codeberg.org/setnex-org/tritlib/issues
Author-email: Eric Tellier <eric.tellier@newick.fr>
License-Expression: MIT
License-File: LICENSE
Keywords: balanced-ternary,base3,kleene-logic,ternary,trit
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Description-Content-Type: text/markdown

# tritlib

A pure Python library for balanced ternary arithmetic, multi-valued logic, and floating-point representation.

## Overview

Balanced ternary is a base-3 numeral system using digits from {−1, 0, +1}. It represents signed integers without a dedicated sign bit, supports trivial negation by inverting every trit, and simplifies carry propagation in addition. tritlib provides a complete, immutable, type-hinted implementation of balanced ternary arithmetic, five ternary logic systems, and the Tekum tapered precision floating-point format.

## Features

### Core types

- **`Trit`** — Immutable single trit. Arithmetic (negation, multiplication, half/full addition with ternary carry), Kleene K3 logic (`&`, `|`, `~`), consensus and anti-consensus operators. Hashable and comparable.
- **`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+"`).
- **`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.
- **`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).

### Multi-valued logic

Five ternary logic systems, selectable at runtime via a common abstract interface:

| System | Third value semantics | Key difference |
|---|---|---|
| **Kleene (K3)** | Unknown (epistemic) | Default. AND = min, OR = max |
| **Łukasiewicz (L3)** | Indeterminate (ontological) | Z → Z yields P (tautological self-implication) |
| **Heyting (HT)** | Non-proved (constructivist) | ~Z = N (unproved is false) |
| **BI3** | Both true and false (paraconsistent) | Z ∧ Z = N (contradiction resolves downward) |
| **RM3 (R-mingle)** | Relevant entailment | Restricted implication |

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.

### Designed for simulation

tritlib provides the building blocks for balanced ternary processor simulation:

- Ternary carry (N/Z/P) richer than binary carry (0/1)
- `add_with_carry` / `add_saturating` / `sub_saturating` for ALU mode selection
- Shift and rotate operations
- Per-trit access (`__getitem__`) and immutable modification (`set`)
- Sign extraction and absolute value
- Consensus / anti-consensus (trit-level agreement detection)
- Logic system dispatch independent of data types (LMODE selection)
- Tekum floating-point decode/encode for FPU simulation

## Installation

```bash
pip install tritlib
```

Requires Python ≥ 3.10. No external dependencies.

## Usage

### Trit arithmetic

```python
from tritlib import Trit, P, Z, N

t = Trit(1)
print(t)          # "+"
print(-t)         # "-"

# Half-adder: returns (sum, carry)
s, c = P.half_add(P)    # s = N, c = P  (1+1 = 3−1)

# Kleene logic
assert (P & Z) == Z     # true AND unknown = unknown
assert (N | P) == P     # false OR true = true
```

### Arbitrary-precision integers

```python
from tritlib import Trits

a = Trits(42)
b = Trits("+-0+")       # 19 in balanced ternary
print(a + b)             # Trits("+-+-+") == Trits(61)
print(int(a * b))        # 798

q, r = divmod(Trits(13), Trits(4))
assert int(q) * 4 + int(r) == 13

# Division can have negative remainder
q, r = divmod(Trits(20), Trits(6))
assert int(q) * 6 + int(r) == 20
print(int(q))  # 4
print(int(r))  # -4
```

### Fixed-width words

```python
from tritlib import Tryte

w = Tryte(42, width=6)
print(len(w))                 # 6
print(w[0])                   # least significant trit

# Saturating addition
result = Tryte(300, 6).add_saturating(Tryte(300, 6))
print(int(result))            # 364 (clamped to max)

# Carry detection
result, carry = Tryte(300, 6).add_with_carry(Tryte(65, 6))
print(carry)                  # P (positive overflow)
```

### Floating-point (Tekum format)

```python
from tritlib import TFloat, Tryte

# Encode from Python float
tf = TFloat(3.14, width=20)
print(float(tf))              # ≈ 3.14

# Decode from a register word
register = Tryte(1640, 8)
tf = TFloat(register)
print(float(tf))              # 1.0

# Arithmetic
a = TFloat(2.5, width=20)
b = TFloat(1.3, width=20)
print(float(a + b))           # ≈ 3.8
print(float(a * b))           # ≈ 3.25

# Special values
print(TFloat(0.0, width=8))             # 0
print(TFloat(float('inf'), width=8))    # ∞
print(TFloat(float('nan'), width=8))    # NaR
```

### Logic systems

```python
from tritlib import P, Z, N
from tritlib.logic import Kleene, Lukasiewicz, HT, Bochvar, RM3

k = Kleene()
l = Lukasiewicz()

# The single point of divergence:
assert k.imply_op(Z, Z) == Z    # unknown → unknown = unknown
assert l.imply_op(Z, Z) == P    # indeterminate → indeterminate = true

# Context manager
from tritlib import logic_mode

assert Z & N == N
with logic_mode(Bochvar()):
    assert N & Z == Z

assert Z.imply(Z) == Z
with logic_mode(Lukasiewicz()):
    assert Z.imply(Z) == P

assert ~Z == Z
with logic_mode(HT()):
    assert ~Z == N
```

### Logical pluralism

```python
from tritlib import P, Z, N
from tritlib.logic.plural import pluralize

# Evaluate Z → Z across all five logic systems
result = pluralize(lambda a, b: a.imply(b), Z, Z)
print(result.divergent)   # True — logics disagree
print(result.groups)      # {Z: ['K3', 'BI3', 'RM3'], P: ['L3', 'HT']}
print(result.consensus)   # None — no unanimous agreement
```

## Project structure

```
src/tritlib/
├── __init__.py
├── trit.py            # Trit type
├── trits.py           # Trits arbitrary-precision type
├── tryte.py           # Tryte fixed-width type
├── tfloat.py          # TFloat Tekum floating-point type
├── context.py         # Logic mode context manager
└── logic/
    ├── __init__.py
    ├── base.py        # TernaryLogic abstract base class
    ├── plural.py      # Logical pluralism (pluralize)
    ├── bochvar.py     # Bochvar
    ├── heyting.py     # Heyting HT
    ├── kleene.py      # Kleene K3
    ├── lukasiewicz.py # Łukasiewicz L3
    └── rm3.py         # R-mingle RM3
```

## Development

```bash
git clone https://codeberg.org/newick_2/tritlib.git
cd tritlib
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
python -m pytest
```

## Roadmap

- [x] `Trit` type with immutability, arithmetic, hashing, consensus
- [x] Kleene K3 logic on `Trit` (`&`, `|`, `~`)
- [x] `Trits` arbitrary-precision integers with full arithmetic
- [x] `Tryte` fixed-width words with shifts, rotations, saturation
- [x] Five logic systems (K3, L3, HT, BI3, RM3) with common interface
- [x] Logic context manager (`with logic_mode(L3()): result = a & b`)
- [x] Logical pluralism: evaluate across all systems, report convergence/divergence
- [x] Tekum balanced ternary floating-point (encode, decode, arithmetic via float)
- [ ] Native trit-level floating-point arithmetic (Tekum truncation = rounding)
- [ ] Educational step-by-step computation output (carry propagation, partial products)

## License

MIT — see LICENSE file for details.

## Links

- Repository: https://codeberg.org/newick_2/tritlib
- PyPI: https://pypi.org/project/tritlib/
- Tekum paper: https://arxiv.org/abs/2512.10964
- Setnex balanced ternary ISA: https://setnex.org
