stillwater-sc/universal

Universal Numbers Library – Quick Overview

What it is – A header‑only C++ template library that provides plug‑in numeric types you can use instead of the built‑in int, float or double. It implements many non‑standard formats (half, bfloat16, posit, fixed‑point, etc.) and lets you write generic code that works with any of them.

Why it matters for AI / ML – Modern deep‑learning models often run in reduced‑precision formats (e.g. FP16, BF16, posits) to gain speed and cut energy use. Universal gives developers a way to experiment with those formats on any hardware, even when the CPU/GPU does not natively support them. This makes it easier to prototype mixed‑precision kernels, test numerical accuracy, and explore custom formats that could improve inference or training efficiency.

How you use it – Include the header for the type you need, then write your algorithm as a template on a Real type:

#include <universal/number/cfloat/cfloat.hpp>

template<class Real>
Real MyKernel(const Real& a, const Real& b) { return a * b; }

using Real = sw::universal::half;   // pick half‑precision IEEE‑754
Real a = sqrt(2);
Real b = 3.14159;
std::cout << MyKernel(a,b) << '\n';

The same kernel can be compiled with float, posit<16,2>, bfloat16, etc., simply by changing the alias.

Key features

• Wide format support – IEEE‑754 variants (quarter, half, quad), NVIDIA TensorFloat, Google bfloat16, Posits, Fixed‑point, Decimal, Rational, Logarithmic, Interval, Adaptive‑precision, and more.
• Header‑only – No external dependencies; just drop the include/ folder into your project.
• C++20 – Uses modern language features and works with GCC, Clang, MSVC.
• Extensive test suite – Regression tests for accuracy, performance, energy, and reproducibility.
• Tooling – Command‑line utilities, Docker image, VS Code dev‑container, and sample programs for education and benchmarking.
• Open‑source – Licensed under a permissive OSS license, with CI badges, code‑coverage, and a JOSS paper describing the design.

Typical use cases

1. Mixed‑precision deep‑learning kernels – prototype FP16/BF16/Posit arithmetic without waiting for hardware support.
2. Numerical research – study rounding error, reproducibility, or energy‑efficiency of custom number systems.
3. Embedded / edge AI – deploy low‑precision arithmetic on micro‑controllers where only integer hardware exists.
4. Education – interactive demos and tutorials that illustrate how different numeric formats behave.

Getting started

• Pull the Docker image (docker pull stillwater/universal) and run a quick C++ example, or
• Clone the repo, run cmake -DUNIVERSAL_BUILD_ALL=ON .. && make, then include the headers you need.

Community & support – Issues on GitHub, a Google Group forum, and a Slack workspace for developers and researchers.

Citation – If you use the library in a publication, cite the JOSS article (2023) and the related arXiv papers.

---

All information above is taken directly from the repository’s README; no external assumptions have been added.