OpenTernary

Open-source tooling for turning open-weight language models into ternary models, with weights restricted to −1, 0 and +1, and for measuring honestly what that costs.

Get started Try it in 5 minutes

uv tool install openternary --python 3.12   # the command, available everywhere
openternary setup                           # detect your GPU, install a matching PyTorch
openternary                                 # open the full-screen interface

Research software

OpenTernary is an alpha research toolkit (version 0.1.0a2). It can inspect, quantize, calibrate, evaluate and export models, and it records everything it does. No ternary model produced with it has passed its quality gate yet. Expect quantized models to be slow and much worse than the original. See Status for exactly what has and has not been verified.

What it does

• Inspect and plan

  ---

  List the tensors that can be quantized, from file headers alone, with no download or GPU needed. Then preview a quantization plan before anything is written.

  Inspect and plan

• Quantize to ternary

  ---

  Convert every linear layer to {-1, 0, +1} codes with per-tensor or per-group scales. Output is a reloadable fake-quant snapshot, written atomically.

  Quantize

• Calibrate

  ---

  Recover quality layer by layer: learn scales, thresholds or soft-to-hard assignments against the original model's activations. Supports checkpoints and resume.

  Calibrate

• Evaluate and compare

  ---

  Run a fixed smoke benchmark and frozen English/Japanese quality sets. Compare runs under identical conditions against a preregistered quality gate.

  Evaluate and compare

• Export

  ---

  Pack weights to 2 bits each, restore them byte for byte, or bridge to GGUF through llama.cpp's converter. Every artifact carries a manifest with hashes for all its files.

  Export

• CLI, TUI and Python

  ---

  Every command has a versioned --json result, progress events and stable exit codes. The TUI runs the same commands as background jobs, and a Python API exposes the same services.

  Automation

How it fits together

flowchart LR
    M[Open-weight model<br/>Hugging Face id or folder] --> I[inspect / plan]
    I --> Q[quantize<br/>ternary fake-quant]
    Q --> C[calibrate<br/>optional]
    Q --> B[benchmark / quality]
    C --> B
    B --> K[compare<br/>quality gate]
    Q --> E[export<br/>packed · safetensors · GGUF]
    C --> E

Each step writes a run directory that records the config, environment, model revision and results, so another person can see exactly what produced a number. Runs and evidence explains how to read one.

Principles

Measure before optimizing. Every conversion is compared against a fixed baseline, under the same protocol.

Evidence over claims. A finished command (execution: completed) is never reported as a quality pass. Unmeasured memory or speed is null, not 0. Quality gates are fixed before the experiment, not tuned to it.

Quality per byte, not bit-count vanity. Keeping sensitive layers at higher precision is allowed when it preserves much more capability.

Japanese is a first-class metric. The frozen quality sets measure English and Japanese separately.

Where to go next

You want to…	Read
Install OpenTernary and PyTorch for your GPU	Installation
See the whole pipeline work on a laptop, offline	Your first run
Understand what "ternary" means and what it costs	Ternary quantization
Look up a flag	CLI reference
Script OpenTernary or run it in CI	Automation
Know what is proven and what is not	Status