{"id":50455899,"url":"https://github.com/t81dev/t81lib","last_synced_at":"2026-06-01T02:30:56.947Z","repository":{"id":328029288,"uuid":"1113365747","full_name":"t81dev/t81lib","owner":"t81dev","description":"t81lib – Balanced-ternary quantization and arithmetic core for AI and quant workloads in modern C++ and Python.","archived":false,"fork":false,"pushed_at":"2026-02-08T23:28:23.000Z","size":1274,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-09T04:55:42.998Z","etag":null,"topics":["ai","arbitrary-precision","balanced-ternary","big-integer","cpp20","high-assurance","low-level","no-undefined-behavior","performance","quant","quantization","ternary","ternary-arithmetic","ternary-computing","ternary-logic"],"latest_commit_sha":null,"homepage":"https://github.com/t81dev/t81lib","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/t81dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-09T22:01:20.000Z","updated_at":"2026-02-08T23:28:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/t81dev/t81lib","commit_stats":null,"previous_names":["t81dev/t81lib"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/t81dev/t81lib","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t81dev%2Ft81lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t81dev%2Ft81lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t81dev%2Ft81lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t81dev%2Ft81lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/t81dev","download_url":"https://codeload.github.com/t81dev/t81lib/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t81dev%2Ft81lib/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33757790,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","arbitrary-precision","balanced-ternary","big-integer","cpp20","high-assurance","low-level","no-undefined-behavior","performance","quant","quantization","ternary","ternary-arithmetic","ternary-computing","ternary-logic"],"created_at":"2026-06-01T02:30:56.486Z","updated_at":"2026-06-01T02:30:56.934Z","avatar_url":"https://github.com/t81dev.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nREADME.md — Visitor-facing overview, focused onboarding, and first-steps guidance.\n--\u003e\n\n# t81 — Balanced Ternary for AI \u0026 Numerics\n\n\n\n![CI](https://github.com/t81dev/t81lib/actions/workflows/ci.yml/badge.svg)\n![License: MIT](https://img.shields.io/badge/license-MIT-blue)\n![Docs](https://img.shields.io/badge/docs-via%20GitHub%20Pages-brightgreen)\n\n`t81lib` is a modern, header-first C++20 and Python library that brings balanced ternary arithmetic,\npacked ternary GEMMs, Python bindings, and quantization helpers to deterministic numerics and ternary-aware\nAI workflows.\n\n**Featured demo** — [Ternary Quantization on Phi-3-mini: PTQ + QAT (8-10x compression, \u003c10% PPL degradation)](examples/ternary_phi3_ptq_qat_demo.ipynb)\n\n## Getting started for Torch users\n\nIf you are arriving from PyTorch or Hugging Face, start here and treat `t81` as your single entry point:\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install \".[torch]\"\n```\n\n```python\nimport t81 as t8\n\ntensor = t8.torch.TernaryTensor.from_float(weight, threshold=0.45)\noutput = tensor.matmul_input(input_tensor, bias=bias)\n```\n\n# -\u003e Runs 2-4x faster on CPU than FP16 with packed ternary kernels\n\nNext steps: `t8.nn.Linear` for drop-in layers, `t8.convert`/`t8.gguf` for programmatic conversion, and `t81 convert`/`t81 gguf` for CLI flows.\n\n## Minimum viable success\n\n```cpp\n#include \u003ct81/t81lib.hpp\u003e\n\nint main() {\n  using t81::Int;\n  Int sum = Int::from_int(1) + Int::from_int(2);\n  return (sum == Int::from_int(3)) ? 0 : 1;\n}\n```\n\n```python\nimport t81lib\n\nprint(t81lib.BigInt(3) * t81lib.BigInt(7))\n```\n\n## Who is this for?\n\n`t81lib` is for:\n\n- Systems and numerics engineers exploring deterministic or non-binary arithmetic primitives.\n- AI practitioners experimenting with ternary quantization, packed GEMMs, and energy-aware inference.\n- Researchers evaluating size/latency trade-offs beyond FP16/int8 or whose experiments benefit from exact, tryte-precise math.\n\nIt is **not** a drop-in replacement for PyTorch or NumPy, but a focused toolkit for ternary-aware systems.\n\n## Choose your path\n\n- **C++ limb/bigint \u0026 numerics** — build locally, include `\u003ct81/t81lib.hpp\u003e`, and verify the `tests/unit/` suite. Starts: [Quick start](#quick-start) \u0026 [docs/api-overview.md](docs/api-overview.md).\n- **Python quantization \u0026 helpers** — `pip install .[torch]` unlocks `t81lib`/`t81`, NumPy wrappers, and `t81.torch`/`t81.nn`. See [docs/python-install.md](docs/python-install.md) \u0026 [docs/python-api.md](docs/python-api.md).\n- **CLI \u0026 GGUF/QAT workflows** — `t81 convert`, `t81 gguf`, and `t81-qat` (the legacy `t81-convert`/`t81-gguf` aliases still work) automate quantize→export→train flows. Follow [docs/references/cli-usage.md](docs/references/cli-usage.md).\n\n## Highlights\n\n- **Balanced-ternary core**: `t81::Int` (an alias for `t81::core::limb`) ships overflow-aware arithmetic, canonical I/O, and deterministic hashing.\n- **Ternary-friendly GEMMs**: `t81::linalg::gemm_ternary` packs balanced ternary matrices into AVX/NEON-accelerated kernels with alpha/beta semantics mirrored in the Python binding.\n- **Python, CLI, and Torch helpers**: Pybind11 bindings expose quantize/dequantize utilities and `t81.torch`/`t81.nn`, while `t81 convert`, `t81 gguf`, and `t81-qat` (and their legacy `t81-convert`/`t81-gguf` aliases) automate quantize/export/train workflows.\n- **Normative docs \u0026 demos**: Architecture notes, CLI references, and runnable demos live under `docs/`, `examples/`, and `bench/`.\n\n## Quick start\n\n### 1. Build \u0026 test locally\n\n```bash\ngit clone https://github.com/t81dev/t81lib.git\ncmake -S . -B build -DT81LIB_BUILD_TESTS=ON\ncmake --build build -j\nctest --test-dir build --output-on-failure\n```\n\n### 2. Install for Python consumers (optional)\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install \".[torch]\"\n```\n\n`pip install` builds the Python bindings, exposes `t81lib`/`t81`, and pulls the optional `torch` helpers when you request `[torch]`. See [docs/python-install.md](docs/python-install.md) for pipx, CLI helpers, and verification scripts.\n\nOn macOS or other PEP 668-enforced environments, activate a virtualenv before running `pip install \".[torch]\"` (or use `python3 -m pip install --user \".[torch]\" --break-system-packages` if you understand the risks) so pip can install the extra dependencies without hitting the “externally managed environment” error.\n\n### 2a. CLI-friendly Pipx install\n\nIf you prefer shell-level access to the unified `t81` CLI (with `convert`/`gguf` subcommands) plus `t81-qat` and `t81-dequant`, pipx can install the repo and then inject the torch extras:\n\n```bash\npipx install --python python3 /Users/t81dev/Desktop/t81lib\npipx inject t81lib torch transformers accelerate datasets safetensors\n```\n\nPipx doesn’t understand `.[torch]` when pointing at a local directory, so we first install the package from source and then inject the optional dependencies you need (torch, transformers, accelerate, datasets, safetensors). Once that completes, the CLI helpers will run from `~/.local/bin` with the same requirements as `pip install \".[torch]\"`. Continue running `pipx uninstall t81lib` and reinject if you upgrade the repo checkout.\n\n### 3. Consume as a subproject\n\n```cmake\nadd_subdirectory(external/t81lib)\ntarget_link_libraries(my_app PRIVATE t81::t81lib)\n```\n\n```cpp\n#include \u003ct81/t81lib.hpp\u003e\n```\n\n### 4. Use through vcpkg\n\n```bash\nvcpkg install t81lib[tests,benchmarks]:x64-windows\n```\n\n```cmake\nfind_package(t81lib REQUIRED)\ntarget_link_libraries(... t81::t81lib)\n```\n\n## Python \u0026 PyTorch\n\n`pip install .[torch]` unlocks the `t81lib`/`t81` namespace, NumPy quantization helpers, and the `t81.torch`/`t81.nn` layers that mix ternary weights with FP32/BF16 biases. Jump deeper via [docs/python-api.md](docs/python-api.md), [docs/python-cookbook.md](docs/python-cookbook.md), and [docs/torch.md](docs/torch.md).\n\n## GPU backends\n\nOptional CUDA/ROCm backends can be enabled with `-DUSE_CUDA=ON` / `-DUSE_ROCM=ON` so the Python bindings link against the GPU kernels. `t81lib` exposes a compact `TensorMetadata` ABI that carries device, dtype, shape, and stride info, allowing `where`, `clamp`, `lerp`, and `addcmul` to work directly on NumPy arrays or Torch tensors. See [docs/gpu.md](docs/gpu.md), [docs/torch.md](docs/torch.md), and the [GPU dispatch diagram](docs/diagrams/gpu-dispatch.mermaid.md) for build flags, device routing, supported ops, and lifetime details.\n\n## CLI helpers\n\n`t81 convert`, `t81 gguf`, `t81 info`, and `t81-qat` automate quantize→export→train flows with progress reporting and validation hooks (the legacy `t81-convert`/`t81-gguf` names still work). Note: both `t81 convert` (new) and `t81-convert` (legacy) are available for backward compatibility. Browse [docs/references/cli-usage.md](docs/references/cli-usage.md), [docs/diagrams/cli-workflows-mermaid.md](docs/diagrams/cli-workflows-mermaid.md), and [examples/cli-examples.md](examples/cli-examples.md) for recipes.\n\n### Large models \u0026 GGUF streaming\n\nWhen targeting multi-gigabyte models (Llama 3.x or Gemma 3.x checkpoints) you can still run the CLI helpers without triggering macOS’s OOM killer, but you need to pin everything to CPU memory:\n\n- Set `ACCELERATE_DISABLE=1` (and `HF_ACCELERATE_DISABLE=1` when you launch a `transformers` command) so Accelerate never offloads tensors to `meta`/disk and the helpers can call `.to(\"cpu\")`.\n- Prefer `--force-cpu-device-map` or `--device-map none/cpu` so `t81 convert`/`t81 gguf` (and the legacy `t81-convert`/`t81-gguf` wrappers) keep checkpoint shards on host RAM.\n- The Python GGUF reader now streams metadata/tensor infos directly from a file handle, seeks to each tensor block, and only buffers one tensor at a time, so `t81 gguf`/`t81-dequant` (and `t81-gguf`/`t81-dequant` scripts for compatibility) can handle the resulting bundles without reading the entire file into memory.\n\nIf you still see `NotImplementedError: Cannot copy out of meta tensor` or a kernel that dies while building Matplotlib’s font cache, repeat the cache setup from [docs/troubleshooting.md](docs/troubleshooting.md#large-gguf-conversions) (`MPLCONFIGDIR`, `FONTCONFIG_PATH`, etc.) before rerunning the CLI.\n\n### Dequantizing for downstream runtimes\n\nUse the new `t81-dequant` helper (backed by `t81.dequantize_gguf_to_float`) to rewrite a TQ1_0 or TQ2_0 bundle into float32 before handing it to stock llama.cpp, Ollama, or LM Studio builds that lack ternary support:\n\n```bash\nt81-dequant model-tq1.gguf model-compatible-f16.gguf\n```\n\nThat command rewrites the tensors in place while preserving the standard GGUF metadata so the resulting file works with existing loaders. Keep the original `model-tq1.gguf`/`model-tq2.gguf` around for runtimes that already understand TQ tensors, and only run `t81-dequant` when you need immediate compatibility.\n\nFor a zero-disk workaround you can also dequantize on the fly (via `t81.dequantize_gguf_to_float` or a small loader patch) before instantiating `llama_cpp.Llama`; see the docs for an example monkey patch if you want to load `model-tq1.gguf` or `model-tq2.gguf` directly without producing an intermediate copy.\n\n\n## Use cases\n\n- Ternary LLM weight quantization and GGUF exports for Hugging Face + `llama.cpp`.\n- Packed ternary GEMMs for CPU inference and `torch.matmul` comparisons.\n- Deterministic numerics and research-grade arithmetic built atop the same core.\n- Ternary hardware simulation and energy modeling (see [docs/hardware.md](docs/hardware.md)).\n\nSee [Use Cases \u0026 Demos](docs/use-cases.md) for real-world workflows, including the Phi-3-mini ternary notebook.\n\n## Examples\n\nSee [examples/README.md](examples/README.md) for the canonical scripts/notebooks (LLM conversion, GEMM packing, quantization demos, hardware previews, etc.).\n\n## Why ternary?\n\n- Balanced ternary offers ≈1.58 bits of entropy per digit with symmetric overflow semantics and deterministic hashing for `t81::Int`.\n- Balanced ternary trades representational symmetry for determinism and composability, making it easy to reason about ternary algebra while keeping model state portable.\n- Refer to [BENCHMARKS.md](BENCHMARKS.md) for the 15–22× storage/latency wins versus FP16 and [docs/hardware.md](docs/hardware.md) for AVX/NEON/AVX-512 kernel sketches.\n\n## Numeric building blocks\n\n`t81lib` exposes fixed-width ternary integers, big integers, rationals, floats, vectors, and Montgomery helpers that share a single canonical core.\nSee [docs/api-overview.md](docs/api-overview.md) for the full surface described in the umbrella header.\n\n## Stability \u0026 compatibility\n\n- Supported toolchains: C++20-capable Clang/GCC/MSVC (or `pip install`’s compatible CPython builds) with CMake ≥ 3.22; the build auto-detects AVX2/AVX-512/NEON and falls back to portable kernels when those SIMD targets are unavailable.\n- We track the ABI/API surface via `include/t81/t81lib.hpp`; expect the core headers to evolve until we reach a stable v1 release and consult [CHANGELOG.md](CHANGELOG.md) for migration notes.\n\n## Docs \u0026 resources\n\n### Getting started\n\n- [docs/index.md](docs/index.md) — Docs portal (great for GitHub Pages).\n- [docs/python-install.md](docs/python-install.md) — Install python bindings, pipx, and CLI helpers.\n- [docs/python-api.md](docs/python-api.md) \u0026 [docs/python-cookbook.md](docs/python-cookbook.md) — Python recipes.\n- [docs/torch.md](docs/torch.md) — PyTorch integration, `t81.torch`, and `t81.nn`.\n- [docs/references/cli-usage.md](docs/references/cli-usage.md) — CLI workflows for convert/gguf/qat.\n- [docs/quantization-hardening.md](docs/quantization-hardening.md) — Phase 1 hardening checklist and reproducible validation lanes.\n\n### Specs \u0026 design\n\n- [docs/t81lib-spec-v0.1.0.md](docs/t81lib-spec-v0.1.0.md) — Normative contract.\n- [docs/design/](docs/design/) — Deep dives on `limb`, `bigint`, and `montgomery`.\n- [docs/api-overview.md](docs/api-overview.md) — Umbrella helper catalog.\n- [ARCHITECTURE.md](ARCHITECTURE.md) \u0026 [docs/index.md](docs/index.md) — Architecture stories and portal.\n\n### Examples \u0026 testing\n\n- [examples/README.md](examples/README.md) — Canonical scripts and notebooks.\n- [tests/](tests/) \u0026 [bench/](bench/) — Regression suites and throughput gauges.\n- [BENCHMARKS.md](BENCHMARKS.md) — Fashion-MNIST FP32/PTQ/QAT comparison.\n- [CONTRIBUTING.md](CONTRIBUTING.md) \u0026 [CHANGELOG.md](CHANGELOG.md) — Contribution guidance and history.\n\n## Benchmarks\n\nSee [BENCHMARKS.md](BENCHMARKS.md) for the Fashion-MNIST FP32/PTQ/QAT comparison.\nPhi-3 GGUF baseline (TQ1_0, CPU-only, llama.cpp): size 1481.96 MiB, peak RSS 2260.02 MiB, prompt 54.35 ms/token (18.4 tok/s), eval 56.22 ms/token (17.79 tok/s).\n\n```bash\ncmake -S . -B build -DT81LIB_BUILD_BENCH=ON -DT81LIB_USE_GOOGLE_BENCH=ON\ncmake --build build -j\n./build/bench/*\n```\n\n## Contribution \u0026 support\n\n- Open an issue to discuss architecture or API needs.\n- Follow [CONTRIBUTING.md](CONTRIBUTING.md) for branching, formatting, and testing workflows.\n- Reference [docs/design/](docs/design/) when proposing optimizations to ensure semantic safety.\n- Track progress in [CHANGELOG.md](CHANGELOG.md).\n- Security concerns can be reported privately; the repo currently follows a standard disclosure cadence.\n\n## License\n\n`t81lib` is MIT-licensed; see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft81dev%2Ft81lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ft81dev%2Ft81lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft81dev%2Ft81lib/lists"}