tritlib 1.0.0

Balanced ternary arithmetic and multi-valued logic library

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

pip install tritlib

Requires Python ≥ 3.10. No external dependencies.

Usage

Trit arithmetic

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

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

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)

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

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

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

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

• Trit type with immutability, arithmetic, hashing, consensus
• Kleene K3 logic on Trit (&, |, ~)
• Trits arbitrary-precision integers with full arithmetic
• Tryte fixed-width words with shifts, rotations, saturation
• Five logic systems (K3, L3, HT, BI3, RM3) with common interface
• Logic context manager (with logic_mode(L3()): result = a & b)
• Logical pluralism: evaluate across all systems, report convergence/divergence
• 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