Universal: a header-only C++ template library of custom arithmetic plug-in types

| System | Status | More information | |------------|------------|----------------------| | Codacy Code Quality | | Code Quality Assessment | | FOSSA Status | | Open-source license dependency scanner | | GitHub Actions | | Latest Linux/MacOS/Windows builds and regression tests | | Development Branch | | Development Branch | | Regression Status | | Regression Status | | Code Coverage | | Code coverage scanner | | Docker Pulls | | Container pulls | | Awesome C++ | | Awesome C++ Libraries | | JOSS Markdown | | Journal of Open-Source Software paper | | Zenodo | | Zenodo DOI Badge |

The goal of the Universal Numbers Library is to offer alternatives to native integer and floating-point for mixed-precision algorithm development and optimization. Tailoring the arithmetic types to the application's precision and dynamic range enables a new level of application performance and energy efficiency, particularly valuable for embedded applications that need autonomy through intelligent behavior.

Deep Learning algorithms in particular provide a core application vertical where alternative formats and precisions, such as half-precision floating-point and bfloat16, yield speed-ups of two to three orders of magnitude, making rapid innovation in AI possible.

The Universal Library is a ready-to-use header-only library that provides a plug-in replacement for native types and offers a low-friction environment to explore alternatives to IEEE-754 floating-point in AI, DSP, HPC, and HFT algorithms.

The basic use pattern is as simple as:

// bring in the parameterized type of interest, in this case
// a fixed-sized, arbitrary configuration classic floating-point
#include <universal/number/cfloat/cfloat.hpp>

// define your computational kernel parameterized by arithmitic type
template<typename Real>
Real MyKernel(const Real& a, const Real& b) {
    return a * b;  // replace this with your kernel computation
}

constexpr double pi = 3.14159265358979323846;

int main() {
    // if desired, create an application type alias to avoid errors
    using Real = sw::universal::half; // half-precision IEEE-754 floating-point  

    Real a = sqrt(2);
    Real b = pi;
    // finally, call your kernel with your desired arithmetic type
    std::cout << "Result: " << MyKernel(a, b) << std::endl;  
}

The library contains fast implementations of special IEEE-754 formats that do not have universal hardware implementations across x86, ARM, POWER, RISC-V, and GPUs. Special formats such as quarter precision, quarter, half-precision, half, and quad precision, quad, are provided, as well as vendor-specific extensions, such as NVIDIA TensorFloat, Google's Brain Float, bfloat16, or TI DSP fixed-points, fixpnt. In addition to these often-used specializations, Universal supports static and elastic integers, decimals, fixed-points, rationals, linear floats, tapered floats, logarithmic, interval and adaptive-precision integers, rationals, and floats. There are example number system skeletons to get you started quickly if you desire to add your own.

Communication channels

• GitHub Issue: bug reports, feature requests, etc.
• Forum: discussion of alternatives to IEEE-754 for computational science.
• Slack: online chats, discussions, and collaboration with other users, researchers and developers.

Citation

Please cite our work if you use Universal.

Research results using Universal arithmetic types are also available:

1. Reproducibility
2. Iterative Refinement

Lorenz System ODE solver using low-precision posits:

Bibtex records

@article{Quinlan:2024,
    author     = {James Quinlan, E. Theodore L. Omtzigt},
    title      = {Iterative Refinement with Low-Precision Posits},
    journal    = {arXiv:2408.13400},
    year       = {2024},
}

@article{omtzigt2023universal,
  title={Universal Numbers Library: Multi-format Variable Precision Arithmetic Library},
  author={Omtzigt, E Theodore L and Quinlan, James},
  journal={Journal of Open Source Software},
  volume={8},
  number={83},
  pages={5072},
  year={2023}
}

@inproceedings{Omtzigt:2022,
  title        = {Universal: Reliable, Reproducible, and Energy-Efficient Numerics},
  author       = {E. Theodore L. Omtzigt and James Quinlan},
  booktitle    = {Conference on Next Generation Arithmetic},
  pages        = {100--116},
  year         = {2022},
  organization = {Springer}
}

@article{Omtzigt2020,
    author     = {E. Theodore L. Omtzigt and Peter Gottschling and Mark Seligman and William Zorn},
    title      = {{Universal Numbers Library}: design and implementation of a high-performance reproducible number systems library},
    journal    = {arXiv:2012.11011},
    year       = {2020},
}

Talks and Presentations

The following presentations describe Universal and the number systems it contained as of the time of publication.

Slides of a presentation at FPTalks'21

Presentation: Application-Driven Custom Number Systems

Slides of the presentation at CoNGA'22

Presentation: Universal: Reliable, Reproducible, and Energy-Efficient Numerics

A quick description of the structure of the number system parameterization can be found here.

Quick start

Follow the local workflow notes in how-to-run-sanitizers.md.

If you just want to experiment with Universal without cloning and building the source code, there is a Docker container with compilers, cmake, and the library pre-installed:

> docker pull stillwater/universal
> docker run -it --rm stillwater/universal bash
stillwater@container:~$ ieee 1.5
stillwater@container:~$ cat > hello.cpp << 'EOF'
#include <universal/number/posit/posit.hpp>
#include <iostream>
int main() {
    sw::universal::posit<16,2> p = 1.5;
    std::cout << p << '\n';
}
EOF
stillwater@container:~$ g++ -std=c++20 -I/usr/local/include/sw -o hello hello.cpp && ./hello

Here is a quick reference of what the command line tools have to offer.

VS Code Dev Container

For a full development environment with both GCC and Clang, install Docker and the Dev Containers VS Code extension, then open the repository and select Reopen in Container. CMake presets (gcc-debug, clang-release, etc.) are available in the CMake Tools preset selector.

How to build

If you do want to work with the code, the universal numbers software library is built using cmake version v4.2.1. Install the latest cmake. There are interactive installers for MacOS and Windows. For Linux, a portable approach downloads the shell archive and installs it at /usr/local:

> wget https://github.com/Kitware/CMake/releases/download/v4.2.1/cmake-4.2.1-Linux-x86_64.sh
> sudo sh cmake-4.2.1-Linux-x86_64.sh --prefix=/usr/local --exclude-subdir

For Ubuntu, snap will install the latest cmake, and would be the preferred method:

> sudo snap install cmake --classic

The Universal Library is a pure C++ template library without any further dependencies, even for the regression test suites to enable hassle-free installation and use.

Clone the GitHub repo, and you are ready