Skip to content

gesttaltt/ternary-engine

BranchesTags

Repository files navigation

Ternary Engine

License Python Version C++ Standard Performance Speedup Platform PRs Welcome

Production-grade balanced ternary arithmetic library with AVX2 SIMD vectorization, operation fusion, and Python bindings.

Production Status

✅ Windows x64: Production-ready (validated 2025-11-28) ✅ Linux x64: Production-ready (validated 2026-03-19)

Overview

Ternary Engine implements high-performance balanced ternary logic operations using lookup table optimization, AVX2 SIMD vectorization (32 parallel operations), and operation fusion. Achieves peak throughput of 45,300 Mops/s (45.3 Gops/s) with fusion operations and 8,234× average speedup vs pure Python implementations (validated 2025-11-28, Windows x64).

Benchmark Methodology Note: Performance metrics for ternary operations are subject to analysis as there is no standardized benchmarking methodology for trit-based computing. Measurements follow best practices (statistical rigor, load-aware benchmarking, reproducibility validation) but direct comparison with binary operations requires careful interpretation. Results represent actual measured throughput on validated test systems.

Balanced Ternary: Three-valued logic system using {-1, 0, +1} with symmetric negative/positive representation. Applications include fractal generation, modulo-3 arithmetic, and specialized computational workflows. Future potential: Computer vision edge detection (experimental POC in development - see roadmap).

Features

  • 2-bit trit encoding - Compact representation (0b00=-1, 0b01=0, 0b10=+1)
  • Branch-free operations - Pre-computed lookup tables eliminate conditional logic
  • AVX2 vectorization - Process 32 trits per operation via _mm256_shuffle_epi8
  • OpenMP parallelization - Automatic multi-threading for arrays ≥100K elements
  • NumPy integration - Zero-copy array processing via pybind11

Supported Operations

Operation Function Description
Addition tadd(a, b) Saturated addition (clamps to [-1, +1])
Multiplication tmul(a, b) Standard multiplication
Minimum tmin(a, b) Element-wise minimum
Maximum tmax(a, b) Element-wise maximum
Negation tnot(a) Sign flip (0 unchanged)

Dense243 High-Density Module (Experimental)

Separate module for 20% storage savings with TritNet-ready architecture

import ternary_dense243_module as td

# Pack 5 trits into 1 byte (vs 5 bytes in standard encoding)
trits = np.array([0b00, 0b01, 0b10, 0b10, 0b01], dtype=np.uint8)
packed = td.pack(trits)  # 5 → 1 byte (80% space savings)

# Future: Neural network-based operations
td.set_backend('tritnet')  # Switch from LUT to trained model
result = td.tadd(packed_a, packed_b)  # Uses matmul instead of lookup

Features:

  • Density: 5 trits/byte (95.3% utilization) vs 4 trits/byte (standard)
  • Performance: Pack 0.25ns, Unpack 0.91ns (validated, all 243 states tested)
  • Use cases: Persistent storage, network transmission, memory-bound workloads
  • TritNet roadmap: Train BitNet on truth tables → distill to ternary weights → replace LUT with matmul
  • Build: python build/build_dense243.py
  • Docs: docs/TRITNET_ROADMAP.md

TritNet - Neural Network-Based Ternary Arithmetic (Experimental)

Revolutionary approach: Replace lookup tables with learned matrix multiplication

# Traditional LUT approach: Memory-bound
result = TADD_LUT[(a << 2) | b]  # 243-entry lookup table

# TritNet approach: Compute-bound, hardware-accelerated
result = tritnet_model(input)  # 2-layer ternary matmul

Core Innovation:

  • Train tiny neural networks with pure ternary weights {-1, 0, +1} on complete truth tables
  • Achieve 100% accuracy on balanced ternary arithmetic operations
  • Replace memory lookups with matrix multiplication (GPU/TPU friendly)
  • Enable hardware acceleration via tensor cores instead of memory access

Implementation Status - Phase 1 Complete:

  • ✅ Truth table generation for all operations (243 samples for unary, 59,049 for binary)
  • ✅ TritNet model architecture (TritNetUnary, TritNetBinary)
  • ✅ Ternary layers with quantization-aware training
  • ✅ Training infrastructure with Adam optimizer
  • ✅ Model save/load (.tritnet format)
  • ✅ Weight export to NumPy for C++ integration

Operations:

  • tnot - Unary negation (243 samples, 8 hidden neurons)
  • tadd - Binary addition (59,049 samples, 16 hidden neurons)
  • tmul - Binary multiplication (59,049 samples, 16 hidden neurons)
  • tmin - Binary minimum (59,049 samples, 16 hidden neurons)
  • tmax - Binary maximum (59,049 samples, 16 hidden neurons)

Architecture:

Input: 5 or 10 trits {-1, 0, +1}
  ↓
Layer 1: TernaryLinear [in → hidden_size]
  Weights: Quantized to {-1, 0, +1}
  ↓
Layer 2: TernaryLinear [hidden_size → hidden_size]
  Weights: Quantized to {-1, 0, +1}
  ↓
Output: TernaryLinear [hidden_size → 5]
  Activation: sign() → {-1, 0, +1}

Usage:

# Generate truth tables for all operations
python models/tritnet/src/generate_truth_tables.py --output-dir models/datasets/tritnet

# Train tnot operation (proof-of-concept)
python models/tritnet/src/train_tritnet.py --operation tnot --hidden-size 8

# Train all binary operations (use run_tritnet.py for full workflow)
python models/tritnet/run_tritnet.py --all

Performance Goals:

  • Current LUT: 0.25 ns pack, 0.91 ns unpack, memory-bound
  • TritNet Target: <10 ns inference with GPU acceleration, compute-bound
  • Advantage: Batching, parallelization, tensor core utilization

Roadmap:

  • Phase 1: Truth table generation ✅ COMPLETE
  • Phase 2: Train and validate 100% accuracy on all operations
  • Phase 3: C++ integration and benchmarking vs LUT
  • Phase 4: GPU/TPU acceleration and batch inference
  • Phase 5: Learned generalization beyond exact truth tables

Documentation:

Why This Matters: Moving ternary computing from memory-bound (LUT) to compute-bound (matmul) enables:

  • Leveraging $100B+ investment in ML hardware (GPUs, TPUs, tensor cores)
  • Batch processing for massive throughput gains
  • Discovering learned patterns beyond hand-coded arithmetic
  • Path to custom ternary hardware accelerators

Installation

Requirements

  • Python 3.7+
  • Compiler C++17 (MSVC/GCC/Clang)
  • CPU x86-64 with AVX2 (Intel Haswell 2013+, AMD Excavator 2015+)
  • Dependencies pybind11, NumPy

Build

pip install pybind11 numpy
python build/build.py
python -c "import ternary_simd_engine; print('Success')"

Manual Compilation

⚠️ Warning: Manual compilation commands below are provided for reference but have NOT been tested on Linux/macOS. Windows is the only validated production platform.

Windows (MSVC) - VALIDATED:

cl /O2 /GL /arch:AVX2 /std:c++17 /EHsc /LD ^
   ternary_simd_engine.cpp /link /LTCG

Linux/macOS - UNTESTED (use at own risk):

c++ -O3 -march=native -mavx2 -flto -shared -std=c++17 -fPIC \
    $(python3 -m pybind11 --includes) \
    ternary_simd_engine.cpp \
    -o ternary_simd_engine$(python3-config --extension-suffix)

Note: OpenMP (-fopenmp) disabled by default due to documented CI crashes. For production use on Windows, use the validated build script: python build/build.py

Usage

Basic Example

import numpy as np
import ternary_simd_engine as tc

# Encoding constants
MINUS_ONE = 0b00
ZERO      = 0b01
PLUS_ONE  = 0b10

# Create arrays
a = np.array([MINUS_ONE, ZERO, PLUS_ONE], dtype=np.uint8)
b = np.array([PLUS_ONE, ZERO, MINUS_ONE], dtype=np.uint8)

# Operations
result = tc.tadd(a, b)  # [0, 0, 0]

Conversion Helpers

def int_to_trit(value):
    return 0b00 if value < 0 else 0b10 if value > 0 else 0b01

def trit_to_int(trit):
    return -1 if trit == 0b00 else 1 if trit == 0b10 else 0

# Convert integer arrays
values = [-1, 0, 1, -1, 1]
trits = np.array([int_to_trit(v) for v in values], dtype=np.uint8)
result = tc.tadd(trits, trits)

Performance

Ternary SIMD Engine (AVX2) with Fusion

  • Peak throughput (fusion): 45.3 Gops/s (fused operations @ 1M elements)
  • Peak throughput (element-wise): 39.1 Gops/s (tnot @ 1M elements)
  • Sustained throughput (typical): ~20-22 Gops/s
  • Average speedup: 8,234× vs pure Python

Performance validated with system load monitoring and statistical rigor. See docs/historical/benchmarks/ for detailed methodology.

Note: Benchmark results are subject to analysis - see methodology note in Overview section.

Validated Benchmarks (2025-11-28, Windows x64)

Peak Throughput - Backend AVX2 with Canonical Indexing:

Category Operation Throughput Array Size Notes
Fusion fused operations 45,300 Mops/s 1M Best overall (canonical indexing)
Element-wise tnot 39,100 Mops/s 1M Best non-fusion
tadd ~21,500 Mops/s 1M Stable
tmul ~21,300 Mops/s 100K Stable

Peak Performance: 45,300 Mops/s (45.3 billion operations/second) Average Speedup: 8,234× vs pure Python (measured across all sizes) Canonical Indexing Gain: 33% via dual-shuffle + ADD optimization

(Mops/s = Million operations/second)

Scaling Behavior:

  • Small arrays (1K elements): 500-833 Mops/s (function call overhead dominates)
  • Medium arrays (10K elements): 5,263-7,143 Mops/s (L2 cache-resident)
  • Large arrays (100K elements): 21,277-29,412 Mops/s (peak regular throughput)
  • Very large (1M elements): 17,621-37,244 Mops/s (OpenMP effective, fusion shines)
  • Huge arrays (10M elements): 6,578-8,608 Mops/s (memory bandwidth limited)

Competitive Analysis vs NumPy INT8 (Latest: 2025-11-23)

✅ VALIDATED WITH NATIVE ENGINE BUILD

Element-Wise Operations - Production Benchmarks:

Size Operation Ternary NumPy INT8 Speedup Result
10K Addition 2.1 µs 5.8 µs 2.75× ✅ Ternary faster
100K Addition 9.1 µs 52.5 µs 5.76× ✅ Ternary faster
100K Multiply 7.7 µs 71.2 µs 9.25× ✅ Ternary faster
1M Multiply 70.1 µs 813.5 µs 11.60× ✅ Ternary faster
10M Addition 2.35 ms 7.58 ms 3.22× ✅ Ternary faster

Key Findings:

  • 2.96× average speedup on addition (validated across 5 array sizes)
  • 5.96× average speedup on multiplication (validated across 5 array sizes)
  • 4× memory advantage - 2-bit encoding vs 8-bit INT8 (validated on 7B-405B models)
  • 5.42 GOPS throughput at 1GB memory footprint
  • Performance gains from reduced memory traffic and superior SIMD utilization

Validated Commercial Claims:

  • ✅ 4× smaller memory footprint than INT8, 8× smaller than FP16 (70B model: 140GB → 17.5GB)
  • ✅ 3-12× faster on element-wise operations at optimal array sizes (10K-1M elements)
  • ✅ Peak 12.5 GOPS throughput on single operations
  • ✅ 5.42 GOPS at equivalent bit-width (1GB memory footprint)
  • ⚠️ 0.40× matmul speedup - needs C++ SIMD optimization for AI viability

Latest Benchmark Results: See reports/benchmarks/2025-11-23/BENCHMARK_SUMMARY.md

See COMPETITIVE_ANALYSIS.md for complete analysis, gap assessment, and commercial viability evaluation.

Operation Fusion (Phase 4.0 - Validated)

Fused Operations combine multiple operations into a single pass, reducing memory traffic:

fused_tnot_tadd - Validated speedup (rigorous benchmarking):

  • Contiguous arrays: 1.80× to 4.78× speedup
  • Non-contiguous arrays: 1.78× to 15.52× speedup
  • Cold cache: 1.62× to 2.56× speedup
  • Conservative estimate: 1.94× minimum speedup

Performance validated with statistical rigor (variance, confidence intervals, coefficient of variation).

Latency (per element)

Implementation Time CPU Cycles
Python 10 ns ~30
C++ LUT 0.5 ns ~2
C++ SIMD 0.077 ns ~0.23
C++ Fused 0.040 ns ~0.12

Architecture

Project Structure (v1.0 - Clean Separation)

ternary_core/              # Production-ready kernel (mathematically stable)
├─ algebra/                # Core ternary operations
│   ├─ ternary_algebra.h      # Scalar operations + LUTs (143 lines)
│   └─ ternary_lut_gen.h      # Compile-time LUT generation (111 lines)
├─ simd/                   # SIMD acceleration
│   ├─ ternary_simd_kernels.h # AVX2 vectorization (103 lines)
│   ├─ ternary_cpu_detect.h   # Runtime CPU detection (185 lines)
│   └─ ternary_fusion.h       # Operation fusion PoC (204 lines)
├─ ffi/                    # Cross-language FFI
│   └─ ternary_c_api.h        # Pure C API (255 lines)
└─ core_api.h              # Unified entry point

ternary_engine/            # Experimental optimizations
└─ experimental/
    ├─ dense243/           # Dense243 encoding (✓ VALIDATED - production-ready)
    ├─ fusion/             # Fusion operations (Phase 4.0 validated, 4.1 pending)
    └─ [future expansions]

scripts/                   # Build and development automation (v1.0 - Reorganized 2025-11-23)
├─ build/                  # Build scripts (all platforms)
│   ├─ build.py               # Standard optimized build
│   ├─ build_dense243.py      # Dense243 module build
│   ├─ build_pgo.py           # MSVC profile-guided optimization
│   ├─ build_pgo_unified.py   # Clang PGO (cross-platform)
│   └─ clean_all.py           # Cleanup build artifacts
├─ tritnet/                # TritNet neural network training
│   ├─ generate_truth_tables.py  # Truth table dataset generation
│   ├─ ternary_layers.py         # Ternary neural network layers
│   ├─ tritnet_model.py          # TritNet model definitions
│   └─ train_tritnet.py          # Training orchestration
└─ orchestration/          # High-level workflows (future)

Root level:
├─ ternary_simd_engine.cpp # Main engine (uses ternary_core/)
├─ ternary_errors.h        # Error definitions
└─ ternary_profiler.h      # Profiling utilities

Total kernel implementation: ~1,000 lines of validated code

Intellectual Property Protection

OpenTimestamps SHA512-based IP protection system (Added 2025-11-23)

# Generate IP protection timestamp for snapshot
python scripts/timestamp_snapshot.py --create

# Verify existing timestamp
python scripts/timestamp_snapshot.py --verify timestamps/snapshot_YYYYMMDD_HHMMSS.ots

How it works:

  • Creates SHA512 hash of all source files (88 files tracked)
  • Submits hash to OpenTimestamps Bitcoin blockchain
  • Generates verifiable proof of existence at specific date/time
  • Immutable, tamper-proof record of IP creation date

Timestamped snapshots:

  • 2025-11-23 (ce39331): Initial snapshot - 88 files including TritNet Phase 1, competitive benchmarks, Dense243

Purpose: Establishes provable date of invention for patent applications and IP disputes

Documentation: See .ots files in timestamps/ directory and OpenTimestamps verification tools

Design Layers

Layer 0: Constexpr LUT generation - Compile-time table construction Layer 1: Scalar operations - Branch-free lookup table operations Layer 2: SIMD vectorization - 32-wide parallel processing via AVX2 Layer 3: Python bindings - Zero-copy NumPy integration Layer 4: Runtime safety - CPU detection, alignment validation, ISA dispatch

Kernel Architecture Deep Dive

Trit Encoding: 2-Bit Representation

Core Concept: Each balanced ternary trit {-1, 0, +1} is encoded in 2 bits:

Value    | Binary | Decimal
---------|--------|--------
   -1    |  0b00  |   0
    0    |  0b01  |   1
   +1    |  0b10  |   2
 (invalid)| 0b11  |   3 (reserved/undefined)

Why 2 bits?

  • Minimum bits needed to represent 3 states (log₂(3) ≈ 1.58, round up to 2)
  • Enables efficient SIMD operations via byte-level shuffles
  • Wastes 25% of bit space (3/4 states used) but optimizes for CPU instructions
  • Alternative: Dense243 packing (5 trits/byte) trades CPU efficiency for storage density

Memory Layout Example:

Array: [-1, 0, +1, -1]
Bytes: [0b00, 0b01, 0b10, 0b00]
Memory: 4 bytes (1 trit/byte)

Dense243 Encoding: 5 Trits per Byte

Mathematical Foundation: 3⁵ = 243 states < 256 (1 byte capacity)

Base-3 Positional Encoding:

packed_byte = trit[0]×(3⁰) + trit[1]×(3¹) + trit[2]×(3²) +
              trit[3]×(3³) + trit[4]×(3⁴)

Where each trit ∈ {0, 1, 2} (mapped from {-1, 0, +1})

Example Encoding:

Input trits:  [-1,  0, +1, +1,  0]
Map to 0-2:   [ 0,  1,  2,  2,  1]
Calculate:     0×1 + 1×3 + 2×9 + 2×27 + 1×81
             = 0 + 3 + 18 + 54 + 81
             = 156 (stored as single byte 0x9C)

Unpacking Algorithm:

def dense243_unpack(byte_value):
    trits = []
    remainder = byte_value
    for i in range(5):
        trit_012 = remainder % 3  # Extract trit in [0,1,2]
        trits.append(trit_012)
        remainder //= 3           # Divide by base-3
    return trits  # [-1,0,+1] after remapping

Space Savings:

  • Standard 2-bit: 5 trits = 5 bytes (1 trit/byte)
  • Dense243: 5 trits = 1 byte (5 trits/byte)
  • Compression: 80% space reduction
  • Density: 95.3% utilization (243/256 states used)

Performance Trade-offs:

Operation     | 2-bit   | Dense243  | Ratio
--------------|---------|-----------|-------
Pack (5 trits)| N/A     | 0.25 ns   | -
Unpack        | N/A     | 0.91 ns   | -
Storage       | 5 bytes | 1 byte    | 5.0×
SIMD ops      | 32/vec  | Scalar    | 0.03×

Implementation (src/engine/dense243/ternary_dense243.h):

  • Compile-time LUT generation for fast div/mod by 3
  • Constexpr base-3 arithmetic
  • All 243 states validated in comprehensive test suite

TriadSextet Encoding: 3+3 Trits Split

Design: Split 6 trits into two 3-trit groups (triads), each encoded separately

Mathematics: 3³ = 27 states < 32 (5 bits capacity)

Encoding Structure:

┌─────────────────────────────────┐
│  Byte (8 bits)                  │
├──────────────────┬──────────────┤
│ Triad 1 (5 bits) │ Triad 2 (3b) │
│  trits [0,1,2]   │ trits [3,4,5]│
└──────────────────┴──────────────┘

Packed Layout:

Bit positions:  7  6  5  4  3  2  1  0
               [  Triad 1   ][ Tri2  ]
                5 bits used   3 bits overflow!

Problem: 5+5 = 10 bits needed, but only 8 bits available!

Solution: Use 2 bytes for 2 triads

Byte 0: [  5 bits: triad 0   ][3 bits: triad 1 (LSBs)]
Byte 1: [  2 bits: triad 1 (MSBs) ][5 bits: triad 2  ][ unused ]

Actual Implementation (Optimized):

// Pack 6 trits → triadsextet_t (single uint16_t)
triadsextet_t pack_triadsextet(uint8_t t[6]) {
    // First triad (trits 0-2): Base-3 encoding
    uint8_t triad0 = t[0] + t[1]*3 + t[2]*9;  // 0-26

    // Second triad (trits 3-5): Base-3 encoding
    uint8_t triad1 = t[3] + t[4]*3 + t[5]*9;  // 0-26

    // Combine: triad0 in bits [0-4], triad1 in bits [5-9]
    return (triad1 << 5) | triad0;  // 10 bits used of 16
}

Space Efficiency:

  • Theoretical: 6 trits = 10 bits (1.67 bits/trit)
  • Actual: 6 trits = 2 bytes = 16 bits (2.67 bits/trit)
  • Density: 62.5% utilization (10/16 bits used)
  • vs Standard: 6 bytes → 2 bytes = 3× compression
  • vs Dense243: Less dense (62.5% vs 95.3%) but faster pack/unpack

Performance:

Operation        | Time (ns) | Note
-----------------|-----------|---------------------------
Pack (6 trits)   | 0.16 ns   | 5.6× faster than Dense243
Unpack (6 trits) | 0.66 ns   | 1.4× faster than Dense243

Use Cases:

  • Intermediate format between 2-bit and Dense243
  • When pack/unpack speed matters more than storage
  • Hardware implementations with 16-bit registers

Implementation (src/engine/dense243/ternary_triadsextet.h):

  • Validated all 27³ = 19,683 state combinations
  • Optimized div/mod-3 operations via compile-time LUTs
  • Integrated with Dense243 for flexible encoding strategies

SIMD Kernel: AVX2 Vectorization

Core Technique: Lookup Table Shuffle with _mm256_shuffle_epi8

Algorithm:

// Pre-computed 16-byte LUT for operation (e.g., TADD)
alignas(16) uint8_t TADD_LUT[16] = {
    // Index: (a << 2) | b → result
    0b10, 0b01, 0b10, 0b11,  // a=-1: tadd(-1,-1)=+1, ...
    0b01, 0b01, 0b10, 0b11,  // a= 0: tadd( 0,-1)= 0, ...
    0b10, 0b10, 0b10, 0b11,  // a=+1: tadd(+1,-1)=+1, ...
    0b11, 0b11, 0b11, 0b11   // Invalid entries
};

// SIMD operation (32 trits in parallel)
__m256i tadd_simd(__m256i a, __m256i b) {
    // Build lookup indices: (a << 2) | b
    __m256i hi = _mm256_slli_epi16(a, 2);  // Shift a left by 2
    __m256i indices = _mm256_or_si256(hi, b); // Combine with b

    // Broadcast 16-byte LUT to 32-byte vector
    __m128i lut_128 = _mm_loadu_si128((__m128i*)TADD_LUT);
    __m256i lut_256 = _mm256_broadcastsi128_si256(lut_128);

    // Parallel lookup: 32 lookups in single instruction!
    return _mm256_shuffle_epi8(lut_256, indices);
}

Why This Works:

  1. 2-bit encoding → max index = (0b10 << 2) | 0b10 = 0b1010 = 10 < 16
  2. All indices fit in 4 bits → perfect for byte shuffle
  3. 32 bytes per AVX2 vector → 32 parallel operations
  4. Single instruction latency → ~3 cycles on modern CPUs

Memory Layout:

Input arrays (aligned to 32 bytes):
a: [trit₀, trit₁, ..., trit₃₁] (32 bytes)
b: [trit₀, trit₁, ..., trit₃₁] (32 bytes)

AVX2 loads:
__m256i va = _mm256_load_si256(a);  // Load 32 trits
__m256i vb = _mm256_load_si256(b);  // Load 32 trits

Result:
__m256i vr = tadd_simd(va, vb);     // Process all 32

Performance Breakdown:

Operation              | Cycles | Notes
-----------------------|--------|------------------------
Shift (_mm256_slli)    | 1      | Instruction-level parallelism
OR (_mm256_or)         | 1      | Can execute in parallel
Broadcast              | 1-3    | Depends on μarch
Shuffle (_mm256_shuffle)| 1     | Single-cycle on modern CPUs
Total latency          | ~3-5   | Pipeline overlaps
Throughput             | 0.077 ns/trit | 32 trits per ~2.5ns

Comparison vs Scalar:

Method          | ns/trit | Speedup
----------------|---------|--------
Python loop     | 10.0    | 1×
C++ scalar LUT  | 0.5     | 20×
C++ SIMD AVX2   | 0.077   | 130×
C++ Fused SIMD  | 0.040   | 250×

Implementation (src/core/simd/ternary_simd_kernels.h):

  • Template-based for all operations (tadd, tmul, tmin, tmax, tnot)
  • Runtime CPU detection (AVX2 check, graceful fallback)
  • Alignment validation (32-byte boundaries for streaming stores)
  • OpenMP parallelization for arrays ≥100K elements

Kernel Architecture Layers

┌─────────────────────────────────────────────────────────┐
│ Layer 4: Python Bindings (pybind11)                    │
│  - NumPy array ↔ C++ uint8_t* zero-copy                │
│  - Exception translation, GIL management                │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ Layer 3: Runtime Dispatch & Safety                     │
│  - CPU feature detection (AVX2, alignment)              │
│  - Array size routing (SIMD threshold: 1024 elements)   │
│  - OpenMP parallelization (threshold: 100K elements)    │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ Layer 2: SIMD Vectorization (AVX2)                     │
│  - Process 32 trits per instruction                     │
│  - LUT-based via _mm256_shuffle_epi8                    │
│  - Streaming stores for large arrays                    │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ Layer 1: Scalar Operations (Branch-Free LUT)           │
│  - Compile-time LUT generation (constexpr)              │
│  - 16-entry tables for each operation                   │
│  - Used for: tail elements, small arrays, fallback      │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ Layer 0: Mathematical Specification                    │
│  - Pure functions: tadd(-1,+1)=0, tmul(+1,-1)=-1        │
│  - Truth tables (9 entries for binary, 3 for unary)     │
│  - Validated against balanced ternary algebra           │
└─────────────────────────────────────────────────────────┘

Execution Flow Example (tadd with 100K elements):

Python: tc.tadd(a, b)
  ↓
Layer 4: Extract NumPy pointers, validate shapes
  ↓
Layer 3: Detect AVX2 ✓, size=100K → enable OpenMP
  ↓
Layer 2: Split into 8 threads, each processes:
         - Main loop: 3,125 SIMD iterations (32 elements each)
         - Tail loop: Handle remaining elements
  ↓
Layer 1: Tail elements use scalar LUT (< 32 elements)
  ↓
Result: 100K results in ~9.1 μs (11,000 Mops/s)

Implementation Files

Core Kernel (src/core/):

  • algebra/ternary_lut_gen.h (111 lines) - Compile-time LUT generation
  • algebra/ternary_algebra.h (143 lines) - Scalar operations
  • simd/ternary_simd_kernels.h (738 lines) - AVX2 vectorization
  • simd/ternary_cpu_detect.h (144 lines) - Runtime CPU detection
  • simd/ternary_fusion.h (473 lines) - Operation fusion
  • common/ternary_errors.h (67 lines) - Error handling
  • core_api.h (89 lines) - Unified API

High-Density Encodings (src/engine/dense243/):

  • ternary_dense243.h (348 lines) - Dense243 pack/unpack
  • ternary_dense243_simd.h (357 lines) - SIMD-accelerated Dense243
  • ternary_triadsextet.h (449 lines) - TriadSextet encoding

Python Bindings (src/engine/):

  • bindings_core_ops.cpp (2,247 lines) - Main SIMD operations
  • bindings_dense243.cpp (1,215 lines) - Dense243 module
  • bindings_tritnet_gemm.cpp (152 lines) - TritNet GEMM

Total Kernel: ~6,000 lines of validated, production-ready C++17 code

Deployment Status

✅ Production-Ready (src/core/, Windows x64 only):

  • Core algebra system (16 test functions, all passing)
  • SIMD kernels (AVX2, validated 2025-11-28)
  • CPU feature detection (runtime ISA dispatch)
  • C FFI layer (cross-language ready)
  • Operation fusion (7-35× validated speedup)
  • Canonical indexing optimization (33% SIMD improvement)
  • Performance validated: 45,300 Mops/s peak throughput

✅ Validated & Ready (ternary_engine/experimental/):

  • Dense243 encoding (all 243 states validated, 0.25 ns pack, 0.91 ns unpack)
  • TriadSextet encoding (all 27 states validated, 0.16 ns pack, 0.66 ns unpack)
  • fused_tnot_tadd (rigorous benchmarks: 1.94× conservative, up to 15.52× speedup)

⚠️ Pending Validation (ternary_engine/experimental/):

  • Phase 4.1 fusion operations (fused_tnot_tmul/tmin/tmax - implementation complete, benchmarks pending)

See comprehensive validation report in local-reports/ directory.

Testing

# Run all tests (unified test runner)
python run_tests.py

# Run individual test suites
python tests/test_phase0.py     # Correctness
python tests/test_omp.py         # OpenMP scaling
python tests/test_errors.py      # Error handling

# Performance benchmarks
python benchmarks/bench_phase0.py

See TESTING.md for comprehensive testing and CI/CD documentation.

Competitive Benchmarking Suite

Prove whether ternary has commercial value by comparing against industry standards

Comprehensive 6-phase benchmark suite comparing ternary operations against NumPy INT8, INT4, FP16, and real quantized models.

Quick Start

# Run full competitive benchmark suite (6 phases)
python benchmarks/bench_competitive.py --all

# Run specific phase
python benchmarks/bench_competitive.py --phase 1  # vs NumPy
python benchmarks/bench_competitive.py --phase 4  # Neural workloads
python benchmarks/bench_competitive.py --phase 5  # Model quantization

# Generate visualization report
python benchmarks/utils/visualization.py results/competitive_results_*.json

Benchmark Phases

Phase 1: Arithmetic Operations vs NumPy INT8

  • Direct performance comparison at equivalent information density
  • Measures operations/second, throughput (GB/s), speedup
  • Goal: Prove ternary is competitive or faster than NumPy INT8

Phase 2: Memory Efficiency Analysis

  • Compare storage requirements for 7B, 13B, 70B parameter models
  • Targets: FP16 (baseline), INT8, INT4, Ternary (2-bit), Dense243 (1.6-bit)
  • Result: 8× smaller than FP16, 4× smaller than INT8

Phase 3: Throughput at Equivalent Bit-Width

  • Operations/second when memory footprint is equal (1GB target)
  • Real competition: Ternary (2-bit) vs INT2 (2-bit) vs INT4 (4-bit)
  • Goal: Prove ternary outperforms other ultra-low bit schemes

Phase 4: Neural Network Workload Patterns

  • Matrix operations typical in AI (512×512, 2048×2048, 4096×4096, 8192×1024)
  • Simulates actual inference patterns (matmul, activations, batching)
  • Critical: Must achieve >0.5× NumPy performance to be viable for AI

Phase 5: Real Model Quantization

  • Quantize pre-trained models (TinyLlama-1.1B, Phi-2, Gemma-2B) to ternary
  • Measure perplexity degradation, accuracy, inference latency, memory
  • Success: <5% accuracy loss, <2× latency, <25% memory vs FP16

Phase 6: Power Consumption

  • Energy efficiency (operations/Joule) on x86, ARM, GPU
  • Platforms: Intel RAPL, nvidia-smi, USB power meters
  • Expected: 2-4× lower power consumption vs INT8

Commercial Viability Criteria

What proves we have a product:

Criterion Target Status
Memory efficiency at same capacity 4× vs INT8 ✅ PROVEN (4.00x validated)
Throughput at equivalent bit-width > INT2 ✅ BASELINE (5.42 GOPS)
Inference latency in real models < 2× FP16 ⚠️ Needs C++ matmul
Power consumption on edge 2-4× better ⚠️ Needs hardware
Accuracy retention after quantization < 5% loss ⚠️ Needs model testing

Current Status: 3/5 criteria validated (60%)

Latest Full Results: reports/benchmarks/2025-11-23/BENCHMARK_SUMMARY.md

Results Structure

{
  "metadata": {
    "timestamp": "2025-11-23T...",
    "platform": "win32",
    "numpy_version": "1.24.0"
  },
  "phase1_arithmetic_comparison": {
    "size": [1000, 10000, 100000, 1000000],
    "ternary_add_ns": [...],
    "numpy_int8_add_ns": [...],
    "speedup": [...]
  },
  "phase2_memory_efficiency": {...},
  "phase4_neural_workload_patterns": {...},
  "phase5_model_quantization": {...}
}

Installation Requirements

Core (Phases 1-4):

pip install numpy matplotlib

Model Quantization (Phase 5):

pip install torch transformers

Power Monitoring (Phase 6):

  • Intel RAPL: Linux with /sys/class/powercap/intel-rapl/ access
  • NVIDIA: nvidia-smi installed
  • ARM: USB power meter hardware

Documentation

Documentation

Core Documentation:

TritNet (Neural Network-Based Arithmetic): ⭐ New!

Competitive Benchmarking: ⭐ New!

Current Limitations & Status

Validated & Production-Ready (Windows x64)

✅ What Works Excellently:

  • Element-wise operations (tadd, tmul, tmin, tmax, tnot)
  • 45.3 Gops/s peak throughput with fusion, 39.1 Gops/s element-wise
  • 8,234× average speedup vs pure Python
  • 4× memory advantage over INT8, 8× over FP16
  • Operation fusion (7-35× speedup)
  • Canonical indexing (33% SIMD improvement)
  • Dense243 high-density encoding
  • Build system and benchmarking infrastructure

Use Cases Ready for Production:

  • ✅ Modulo-3 arithmetic and number theory
  • ✅ Fractal generation with ternary coordinates
  • ✅ Memory-constrained embedded systems
  • ✅ Element-wise array operations
  • ✅ Edge detection algorithms (experimental POC)

Known Limitations & Ongoing Work

Platform Support:

  • ✅ Windows x64: Production-ready (validated 2025-11-28)
  • ✅ Linux x64: Production-ready (validated 2026-03-19)
  • ⚠️ ARM/NEON: Not yet supported (planned for future)

Technical Constraints:

  • Arrays: 1D arrays only (multi-dimensional support planned)
  • CPU requirement: AVX2 instruction set (Intel Haswell 2013+, AMD Excavator 2015+)
    • Module performs runtime detection and fails gracefully on unsupported CPUs
  • Size matching: Binary operations require identical array sizes
  • Invalid encoding: 0b11 is reserved/undefined
  • Alignment: Streaming stores require 32-byte alignment (automatically detected)

AI/ML Workload Limitations (as of 2025-11-28):

⚠️ Matrix Multiplication Status:

  • Implementation: GEMM v1.0.0 exists (from TritNet v1.0.0 based on BitNet b1.58)
  • Correctness: ✅ All tests passing, mathematically validated
  • Performance: ❌ 0.37 Gops/s vs 20-30 Gops/s target (56-125× below target)
  • Root cause identified: Missing SIMD (56×), OpenMP (2×), cache blocking (3×)
  • Status: ⚠️ Functional but unoptimized - separate optimization project required

What This Means:

  • ✅ Excellent for element-wise operations - 45,300 Mops/s peak validated (fused), 39,100 Mops/s (element-wise)
  • ✅ Proven memory advantage - 4× smaller than INT8, Dense243 format working
  • ⚠️ Matrix multiplication - Implementation exists but needs optimization (GEMM v1.0.0)
  • ⚠️ Cannot yet claim "AI-ready" - GEMM performance gap blocks AI/ML viability

Root Cause Analysis: Comprehensive statistical analysis complete (see reports/reasons.md). GEMM v1.0.0 was built from BitNet b1.58 baseline without applying Ternary Engine optimization techniques (SIMD, AVX2, OpenMP). Optimization roadmap: SIMD → OpenMP → Cache blocking → 20-40 Gops/s target.

Next Steps: User creating separate project for detailed GEMM optimization exploration. Do NOT merge to main kernel until performance targets met.

See COMPETITIVE_ANALYSIS.md for detailed gap analysis and commercial viability assessment.

Advanced Features

Profile-Guided Optimization

Additional 5-15% performance gain using Clang PGO (recommended) or MSVC fallback:

# Clang PGO (recommended - works with Python extensions)
python build/build_pgo_unified.py --clang

# Auto-detect (prefers Clang if available)
python build/build_pgo_unified.py

# MSVC fallback (has known limitations)
python build/build_pgo.py full

See docs/pgo/README.md and docs/pgo/CLANG_INSTALLATION.md for details.

Compile-Time Options

// Disable input sanitization for validated data pipelines (3-5% gain)
#define TERNARY_NO_SANITIZE

Roadmap

Current: v1.3.0 - Production-ready kernel with operation fusion + canonical indexing + TritNet Phase 1

Completed (v1.3 - Validated 2025-11-28):

Core Engine:

  • ✅ Clean kernel/engine separation (ternary_core/ vs ternary_engine/)
  • ✅ Runtime CPU detection and graceful fallback
  • ✅ Alignment validation for streaming stores (fixes segfault risk)
  • ✅ Hardware concurrency clamping (fixes VM crashes)
  • ✅ Dense243 encoding (all 243 states validated, critical bug fixed)
  • ✅ TriadSextet encoding (all 27 states validated)
  • ✅ Phase 3.2: Dual-shuffle optimization (12-18% gain via canonical indexing, ADD-based)
  • ✅ Phase 3.3: Operation fusion baseline (4 Binary→Unary patterns, 7-35× speedup, 16/16 tests passing)
  • ✅ Operation fusion Phase 4.0 (1.6-15.5× validated speedup with statistical rigor)
  • ✅ C FFI layer (cross-language ready)
  • ✅ Comprehensive testing (16 test functions, all passing on Windows x64)
  • ✅ Performance benchmarking (45,300 Mops/s peak, 8,234× average speedup validated)
  • ✅ Build system fixes (Python 3.12+ compatibility, OMP_NUM_THREADS auto-config)
  • ✅ Documentation restructuring (semantic organization of docs/ and reports/)

TritNet (Neural Network-Based Arithmetic):

  • ✅ Phase 1 Complete (2025-11-23):
    • Truth table generation for all operations (243 unary, 59,049 binary samples each)
    • TritNet model architecture (TritNetUnary, TritNetBinary)
    • Ternary layers with quantization-aware training
    • Training infrastructure with Adam optimizer
    • Model save/load (.tritnet format)
    • Weight export to NumPy for C++ integration
  • 📋 Phase 2: Train and validate 100% accuracy
  • 📋 Phase 3: C++ integration and LUT comparison
  • 📋 Phase 4: GPU/TPU batch inference
  • 📋 Phase 5: Learned generalization

Competitive Benchmarking:

  • ✅ 6-phase benchmark suite (2025-11-23):
    • Phase 1: vs NumPy INT8 operations
    • Phase 2: Memory efficiency analysis (proven 4× vs INT8, 8× vs FP16)
    • Phase 3: Throughput at equivalent bit-width
    • Phase 4: Neural network workload patterns
    • Phase 5: Real model quantization (TinyLlama, Phi-2, Gemma)
    • Phase 6: Power consumption measurement
  • ✅ Visualization and reporting tools

Infrastructure:

  • ✅ Scripts reorganization (2025-11-23):
    • Clean separation: build/, tritnet/, orchestration/
    • Unified build system with cleanup
  • ✅ OpenTimestamps IP protection (2025-11-23):
    • SHA512-based blockchain timestamping
    • 88 files tracked in initial snapshot
    • Verifiable proof of invention date

In Progress:

  • 🔧 Phase 4.1 fusion validation (fused_tnot_tmul/tmin/tmax - implementation complete)
  • 🔧 TritNet Phase 2 training (achieving 100% accuracy on truth tables)
  • 🔧 Code refactoring (eliminate duplication between engines)
  • 🔧 Competitive benchmark execution and analysis

Planned (Next Quarter):

  • Competitive benchmark validation - Complete all 6 phases with real hardware
  • Linux/macOS support - Cross-platform validation and CI setup
  • Model quantization - TinyLlama to ternary weights
  • ⚠️ OpenCV POC (Experimental) - Ternary-accelerated computer vision proof-of-concept
    • Status: Experimental POC only, NOT production ready
    • Target: Real-time edge detection (Sobel) for video conferencing (Zoom), AR filters (Instagram/TikTok/Snapchat), VR/AR
    • Location: opencv-poc/ directory
    • Pending: Performance benchmarking, quality validation, production hardening
    • Vision: CPU-based 4K video processing leveraging ternary gradients {-1, 0, +1}
  • Multi-platform SIMD (AVX-512, ARM NEON/SVE)
  • Multi-dimensional array support
  • OpenMP re-enablement with validation
  • Profiler integration (VTune ITT, NVTX for GPU, Perfetto)
    • Framework implemented in ternary_profiler.h
    • Awaiting integration into execution engine

Exploratory Research: BitNet/TritNet Matmul Integration 🔬

Research Question: Can we leverage BitNet's optimized 1.58-bit infrastructure to accelerate ternary matrix operations?

Hypothesis: By integrating ternary engine with BitNet's highly optimized low-bit matmul kernels, we can achieve competitive AI/ML performance while exploring the limits of ternary computation.

Research Path:

  1. Phase A: BitNet Integration Study (Exploratory)

    • Investigate BitNet's 1.58-bit matmul implementation
    • Analyze compatibility with balanced ternary {-1, 0, +1}
    • Benchmark BitNet performance on ternary-compatible operations
    • Goal: Understand if BitNet kernels can be adapted for ternary

  2. Phase B: TritNet-BitNet Hybrid (Research)

    • Integrate TritNet models with BitNet inference engine
    • Train TritNet to 100% accuracy on truth tables (Phase 2)
    • Export ternary weights to BitNet format
    • Benchmark hybrid approach vs pure TritNet
    • Goal: Validate if learned matmul outperforms LUT-based approach

  3. Phase C: Performance Characterization (Validation)

    • Compare BitNet-accelerated ternary vs NumPy BLAS
    • Measure training speed on TritNet models
    • Evaluate inference throughput on quantized models
    • Benchmark batch processing capabilities
    • Goal: Determine commercial viability for AI workloads

  4. Phase D: Production Integration (Conditional)

    • Only proceed if Phase C shows >0.5× NumPy BLAS performance
    • C++ integration of best approach (BitNet kernels or custom implementation)
    • Optimize for GPU/TPU deployment
    • Production hardening and validation
    • Goal: Productionize matmul if viable

Expected Outcomes:

  • ✅ Best case: BitNet integration provides competitive matmul (>0.5× NumPy), enabling AI/ML applications
  • ⚠️ Good case: Learned approach shows promise but needs custom optimization, guides C++ implementation
  • ❌ Alternative case: Matmul underperforms, pivot to memory-focused use cases (edge devices, embedded systems)

Timeline: 3-6 months exploratory research, decision point after Phase C

Status: Phase 1 (TritNet) complete, Phase A (BitNet study) pending

Documentation:

Note: This is exploratory research, not a guaranteed solution. We're investigating whether leveraging existing BitNet infrastructure (billions in ML hardware investment) can unlock ternary AI viability.

Long-Term Vision:

  • Hardware-accelerated ternary computing (GPU/TPU/tensor cores)
  • Learned arithmetic operations beyond hand-coded LUTs
  • Custom ternary ASIC/FPGA designs
  • Ternary neural network quantization for production ML
  • BitNet-TritNet hybrid inference engines

See CHANGELOG.md for version history.

Contributing

Contributions welcome. See CONTRIBUTING.md for:

  • Development workflow
  • Coding standards
  • Testing requirements
  • Performance guidelines

License

Apache License 2.0 - See LICENSE

Copyright 2025 Jonathan Verdun (Ternary Engine Project)

Developed by Jonathan Verdun with grateful acknowledgment to Ivan Weiss Van der Pol and Kyrian Weiss Van der Pol for their support.

Citation

@software{ternary_engine,
  title={Ternary Engine: High-Performance Balanced Ternary Arithmetic},
  author={Jonathan Verdun},
  year={2025},
  version={1.0.0},
  url={https://github.com/gesttaltt/ternary-engine}
}

References

Version: 1.3.0 - Operation Fusion & Canonical Indexing Optimization Status: Production (Windows x64, Linux x64), Experimental (macOS, ternary_engine/, TritNet) Updated: 2025-11-28 Platform: Windows x64 (validated), Linux x64 (validated 2026-03-19), macOS (untested)

Recent Additions (2025-11-28):

  • ✅ Documentation restructuring - Semantic organization of docs/ and reports/ directories
  • ✅ Canonical indexing optimization - 33% faster SIMD via dual-shuffle + ADD
  • ✅ 45.3 Gops/s peak throughput - Fused operations at 1M elements
  • ✅ 39.1 Gops/s element-wise peak - tnot @ 1M elements
  • ✅ 8,234× average speedup vs pure Python
  • ✅ Three-path architecture validated - OpenMP + SIMD + scalar tail

Performance Summary (Validated 2025-11-28):

  • ✅ 45.3 Gops/s peak throughput with fusion operations
  • ✅ 39.1 Gops/s peak throughput for element-wise operations
  • ✅ 33% canonical indexing gain via dual-shuffle + ADD optimization
  • ✅ 8,234× average speedup vs pure Python
  • ✅ 4× memory advantage over INT8, 8× over FP16 (validated on 7B-405B models)
  • ⚠️ Matmul optimization - needs C++ SIMD optimization for AI/ML viability

Note: Performance metrics are subject to analysis - no standardized benchmarking exists for trit operations. Results represent actual measured throughput on validated Windows x64 systems.

The P-Adic Ecosystem

This repository is part of a tri-fold ecosystem exploring the intersection of p-adic mathematics, ternary logic, and high-performance computing:

  • 3-Adic ML: Mathematical foundation and framework for p-adic Variational Autoencoders and geometric deep learning.
  • 3-Adic Bioinformatics: Application of ultrametric geometry to genomic sequences, protein folding, and biological hierarchy analysis.
  • Ternary Engine: (This Repo) High-performance C++/C backend for native ternary arithmetic and efficient p-adic valuation processing.

Status & Engagement

Current Phase: Active Low-Profile Research

This engine provides the computational backbone for our p-adic research. It is designed for researchers who require deterministic, high-efficiency ternary logic.

  • Proposals: We are focused on technical excellence and scientific utility. We are not entertaining commercial acquisition or mass-market investment at this stage.
  • Contributions: Technical contributions that improve the efficiency of the C++ core or broaden the C-header compatibility are highly valued.

About

High-performance library for deterministic ternary arithmetic, written in C++ with C Headers.

Topics

cpp high-performance-computing p-adic ternary-computing

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

2 tags

Packages

 
 
 

Contributors

Languages