Termux-BitNet (v2.0.0 Sovereign Ternary)

Production-Grade Universal 1.58-Bit (i2_s) On-Device LLM Inference Engine with ARM64 NEON DotProd SIMD & Native Vulkan GPU Acceleration.

🏛️ Executive Engineering Disclosure: The v2.0.0 Sovereign Ternary Breakthrough

termux-bitnet v2.0.0 represents a generational architectural leap from a single-model experimental wrapper into a universal, multi-model 1.58-bit on-device inference runtime.

This release mathematically resolves the notorious ternary numerical collapse ("word salad") that has plagued the global BitNet community, introduces a zero-overhead dynamic activation dispatcher, and breaks mobile memory boundaries by executing 7.45B parameter models on 6GB RAM smartphones without OOM crashes.

📚 Official Academic & Upstream Credibility

• Foundation Technical Whitepaper: AOSF-TR-2026-BITNET-TERNARY-02: Root Cause Analysis of Ternary Numerical Collapse and Dynamic Activation Engine
• Upstream Contributions to Microsoft:
  • microsoft/BitNet #551: Resolved ARM QK=128 stride memory layout desynchronization and word salad.
  • microsoft/BitNet #624: Completed 1x4_32W parallel NEON sdot hardware acceleration kernel and automated Android Termux tooling.
• Upstream Contributions to GGML:
  • ggml-org/whisper.cpp #4089: Mobile heterogeneous GPU-Encoder / CPU-Decoder split-mode architecture.

⚡ Empirical Real-Device Hardware Fleet Scorecard (Ground Truth)

All benchmarks were empirically measured on genuine Samsung Galaxy hardware under unrooted Android Termux Bionic libc environments across 4 canonical 1.58-bit model families:

🔬 Key Technical Breakthroughs in v2.0.0

1. Mathematical Elimination of Ternary Numerical Collapse

Upstream forks historically mapped raw bitfields using (b & 1) - (b >> 1). In Microsoft's official specification, weights are offset by +1 ($w_{\text{stored}} = w_{\text{ternary}} + 1$). The legacy mapping turned the 49.6% inactive zero neurons into +1, causing exponential activation norm explosion across 30 layers. termux-bitnet v2.0.0 enforces canonical dequantization: $$w_{\text{ternary}} = (b & 3) - 1 \implies 00 \to -1,; 01 \to 0,; 10 \to +1$$ Coupled with the extraction and accumulation of 32-byte GGUF tensor trailer weight scales ($S_W = \text{mean}(|W|)$), output logits remain perfectly calibrated.

2. Zero-Overhead Dynamic Activation Dispatcher

Standard runtimes hardcode either SiLU or Squared ReLU. termux-bitnet v2.0.0 inspects the presence of lay.ffn_sub_norm to seamlessly auto-dispatch:

• Microsoft BitNet 2B: Squared ReLU ($\text{relu}(x)^2$) + Sub-LayerNorm.
• Falcon-E-1B & Falcon3-7B: Standard SwiGLU ($\text{SiLU}(x) \cdot \text{up}$) without Sub-LayerNorm.

3. 6GB RAM Smartphone 7.45B Model Execution

Through Zero-Copy mmap weight streaming and bounded KV cache management, 3.05GB model weights are mapped directly from flash storage without duplicating resident set size (RSS), allowing 7.45B parameter LLMs to complete inference on mainstream 6GB RAM devices without triggering Android Low Memory Killer (LMK).

📦 Installation

1. Python SDK (PyPI)

# Inside Android Termux (prerequisites: clang cmake python openblas)
pkg update && pkg install -y clang cmake python openblas

# Install Termux-BitNet and AMEVA-Runtime
pip install --upgrade termux-bitnet ameva-runtime

2. Node.js CLI (npm)

npm install -g termux-bitnet @ameva/runtime

3. One-Touch Native Installer

curl -sSL https://raw.githubusercontent.com/uno-km/termux-bitnet/main/install.sh | bash

🚀 Quickstart Recipes

1. Python Programmatic Inference

from termux_bitnet import BitNetEngine, BitNetConfig

# Configure for real-time Falcon-E-1B or BitNet-2B
config = BitNetConfig(
    model_path="~/.cache/termux-bitnet/models/falcon-e-1b-instruct-i2_s.gguf",
    device="auto",        # "auto", "cpu", or "gpu"
    n_threads=4,
    temperature=0.7,
    top_p=0.95
)

with BitNetEngine(config) as engine:
    print("[Prompt]: Explain the theory of relativity in one sentence.")
    print("[Response]: ", end="", flush=True)
    for token in engine.generate_stream("Explain the theory of relativity in one sentence:"):
        print(token, end="", flush=True)
    print()
    metrics = engine.get_last_metrics()
    print(f"Speed: {metrics.tokens_per_second:.2f} tok/s")

2. Standalone CLI Usage

# Run 1B real-time conversational model
termux-bitnet run -m models/falcon-e-1b-instruct-i2_s.gguf \
  -p "What is the capital of South Korea?" -t 4

# Run 7.45B model on 6GB RAM device
termux-bitnet run -m models/falcon3-7b-instruct-1.58bit-i2_s.gguf \
  -p "Solve this riddle: I speak without a mouth..." -t 4

📑 Supported Pretrained Models

🌐 Ecosystem Links & Documentation

• Official Documentation Portal: https://uno-km.vercel.app/lib/bitnet/
• Foundation Research Lab: https://uno-km.vercel.app/labs/
• License: Apache-2.0
• Governance: AMEVA Open-Source Foundation (AOSF) & @uno-km