Metadata-Version: 2.4
Name: ternary-forge
Version: 1.1.1
Summary: Native balanced-ternary arithmetic, ternary MLP, ternary VM, and trit packing - pure Python/NumPy.
Author: Lexatellah
License-Expression: MIT
Project-URL: Homepage, https://github.com/Lexatellah/ternary-forge
Project-URL: Repository, https://github.com/Lexatellah/ternary-forge
Project-URL: Issues, https://github.com/Lexatellah/ternary-forge/issues
Project-URL: Documentation, https://github.com/Lexatellah/ternary-forge/blob/main/docs/BINARY_ACCIDENT.md
Keywords: ternary,balanced-ternary,machine-learning,neural-network,quantization,virtual-machine,trit
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Interpreters
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

﻿# ternary-forge

**Native balanced-ternary arithmetic, a ternary neural network, a ternary VM, and a trit-packing file format — in pure Python/NumPy.**

Binary is not a law of nature. It is an industrial accident. This repository is a fork in the road.

## Results

| What | Number | Where |
|---|---|---|
| Ternary MLP on MNIST | **93.20%** (float baseline: 92.28%) | `examples/train_mnist.py` |
| Weight storage | **1.58 bits/weight** (float32: 32) | `examples/train_mnist.py` |
| Trit packing | **5 trits/byte**, 99.06% of Shannon optimum | `examples/pack_demo.py` |
| VM | 8-register balanced-ternary ISA, native `NEG` and `SHL3` | `examples/run_vm.py` |

## Install

    pip install -e '.[dev]'

## Run the proof

    python -m pytest -q                  # 11 tests
    python examples/train_mnist.py       # ternary vs float MNIST
    python examples/run_vm.py            # ternary assembly programs
    python examples/pack_demo.py         # 40 KB .trit file, roundtrip

## The argument

See **[docs/BINARY_ACCIDENT.md](docs/BINARY_ACCIDENT.md)** for the citable case: Setun (1958), the 5500FP (2026), Ternary Weight Networks (2016), and the three results above as evidence.

## What this is not

- Not a wrapper around PyTorch. The MLP is hand-written NumPy.
- Not a binary emulator pretending to be ternary. The VM’s `NEG` is one instruction that flips trits.
- Not a toy. The packing format is exhaustive-tested over all 243 five-trit states.

## License

MIT
